3 ms·
"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 ev
by rightbyte 8y ago
"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.
There are two good reasons for this. First, anyone who needs to see code-level
documentation will in most cases be able to and prefer to read the code anyway
...
More importantly however, is that the code and the documentation
cannot get our of sync if there is no documentation. The source code can at
worst be wrong and confusing. The documentation, if not written perfectly, can
lie, and that is a thousand times worse"
This is such baloney. I understand that many programmers want barriers of entry to their chair at the office but rationalizing it is self-deception.
The author is essentially saying to write strcmp() "self-explanatory" rather than the a black box description like:
http://www.cplusplus.com/reference/cstring/strcmp/ http://www.cplusplus.com/reference/cstring/strcmp/
strcmp() is useless without knowing what the return values mean and reading the code to figure it out is way more time consuming than reading the docs.
- abc_lisper 8y agoThis. Most people who think they write self explanatory code are deluding themselves. While others may see architectural and compile time information, the runtime information especially that concerns with generality of the code, and things it does not do (like the complement of a set) are not at all evident. What's clear for one person is not for another. Ancedotally, most people don't write as a good a code they think they are.
- ken 8y agoEven more importantly, the documentation is the contract. Most languages (and especially C) aren't nearly precise enough to declare a function's complete contract using source code. How would you know if strcmp had a bug, if there were nothing that said what it was supposed to do? Without documentation, you're left with merely: the code is supposed to do whatever it happens to do right now. Systems like this are terrible to work on. At best, you have to verify O(n) call points across the entire code base whenever you touch any function. At worst, that interface is already public, and you can't ever "fix" anything.
- theoh 8y agoNo, 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.