4 ms·
No, you have misunderstood. This statement refers to documentation in the form of comments in source files. You are referring to the documentation of interfaces
by theoh 8y ago
No, you have misunderstood. This statement refers to documentation in the form of comments in source files. You are referring to the documentation of interfaces (e.g. manual pages in Unix) which is definitely required.
A gnarly function in C will sometimes be impractical to fully 'comment'. English is too verbose and imprecise compared to the code. But, in particular, inserting uninformative comments that explain simple statements (statements that can be clearly understood by reading the line of code) is a known rookie mistake. It can lead to a case of not being able to "see the wood for the trees"—how the code works is still obscure, but every line has a literal translation in the accompanying comment.
Googling "don't comment code" brings up a number of articles and blog posts discussing this issue. One thing people sometimes say is that comments should explain 'why', not 'what', the code does, e.g. an explanation of what the algorithm is doing, where necessary, rather than a description of each programmatic operation. That kind of comment is like a gloss on what the function is doing, or a conversational explanation of the procedure that the code implements.
Again, this is not about documenting interfaces.
- rightbyte 8y agoI'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.