3 ms·
I'm not too sure the author means about that, even though you interpretation is possible. "When it comes to actually documenting code itself, as opposed to pro
by rightbyte 8y ago
I'm not too sure the author means about that, even though you interpretation is possible.
"When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I've ever known hold a universal sentiment: write self-explanatory code and don't document code except in the places that you cannot make it clear."
I would say eg. Doxygen style function documentation or that strcmp() doc. I linked falls under documents non-programmers wont read.
Hi is emphasizing writing "little" good documentation over "write crap nobody will read". Is it really a good advice to new programmers about documentation?
Can everyone who have spent their career cursing former coworkers that wrote too much code documentation raise their hands. Congrats you were working in heaven.
I'd say when in doubt, write comments. 'How', 'why' and 'what' ... and 'when' and in what order. But that's a matter of taste of course.
- theoh 8y agoThe idea that this advice means "don't bother documenting APIs" is a straw man which isn't worth arguing about. The "non-programmers" phrasing is misleading, I agree, but the widely held sentiment that the author was expressing is recognizably the one about comments in source files. When the algorithm itself really needs verbose documentation, or if the code it's intended to be used for instruction (incorporated into a book, for example), there's always literate programming. The notorious Unix comment mentioned here https://en.m.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_6th_Edition,_with_Source_Code#"You_are_not_expected_to_understand_this" https://en.m.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_... is actually a good example of a situation where a comment is needed to explain the rationale of the code. At the same time, it was clear to the documenter that the situation was too complicated to be made totally clear by the comment alone (or by reading that piece of code in isolation.) That is the kind of situation in which a comment is necessary, but also inadequate. That is the difficult reality behind this advice: comments don't really work that well when you really want them to.
- rightbyte 8y agoYeah OK I agree about not wielding strawmans. Another interesting example on comments is the original implementation of 'cat'. A lot of comments. https://minnie.tuhs.org/cgi-bin/utree.pl?file=PDP7-Unix/cmd/cat.s https://minnie.tuhs.org/cgi-bin/utree.pl?file=PDP7-Unix/cmd/... V2 of Unix had no comments in cat. https://minnie.tuhs.org/cgi-bin/utree.pl?file=V2/cmd/cat.s https://minnie.tuhs.org/cgi-bin/utree.pl?file=V2/cmd/cat.s It's a extreme example, but I know which one i would prefer to debug or modify.