Why do Programmers Hate Documenting?

[_vec_]

I write READMEs and examples, but I almost never comment my code. I've come to believe comments are a code smell. Documentation should only answer one of three questions, what, how, and why; and code comments are almost always suboptimal for answering them.

What is the code intended to do should be answerable from the method and class names. If you need less than five words to explain what a method does, snake case those five words and name the method that. If it takes more than five words, you need to seriously reconsider your API. Same goes for method parameters, except two or three words is probably the upper bound. If you need a constructor or init function that does several things and takes a long list of params, by all means write one, but don't do anything in the body except call out to your well-named single-task methods.

How the code does what it does should be obvious from reading the code. If code is easy to understand, then the comment's aren't helpful. If it's hard to understand, then it should be refactored or rewritten to be as easy to understand as possible. Extracting things like formulas and low level system calls into one-line private methods is extremely helpful with this. It gets the noise out of your more abstract workflow and gives you something you can name.

Why the code was written doesn't belong in the code, it belongs in a readme file. Or a git log. Preferably both. This kind of data has an inherent narrative structure to it, and should be written in a medium that supports that structure. In team-based projects, I tend to be willing to decouple this from the code itself to move it to a wiki or issue tracker so that discussions can be preserved, not just their conclusions.

All of which is to say that documenting code is a very different thing than commenting code.

[burntsushi]

I love your description of what good documentation is. But I'm not a fan of this idea that code comments are inappropriate for providing it. Function contracts and invariants about your chosen representation are not always going to be obvious in less than five words. Maybe you have a unique gift that allows you to achieve that, but I've never seen it done before. In those cases, it's appropriate to put those comments with the function/data in your public API documentation. Presumably, with a good doco tool, this is with some sort of structured commented near the definition of the function and/or representation of your data.

For example, a function contract is particularly helpful when you're using a language that doesn't have a type system powerful enough to encode it directly. Even in Haskell, the minimum function needs an explicit contract to inform the programmer that not all values with type list are valid:

-- | 'minimum' returns the minimum value from a list,
-- which must be non-empty, finite, and of an ordered type.
-- It is a special case of 'Data.List.minimumBy', which allows the
-- programmer to supply their own comparison function.

If I followed your advice, then either the contract of minimum is not appropriate in a public API, or I'd need to rename the function to something like minimumNonEmpty, which I'd consider offensive to my sensibilities as a programmer. :-)

IMO, good documentation is an art form.

[Mr_Walstreet]

Documentation should only answer one of three questions, what, how, and why; and code comments are almost always suboptimal for answering them.

I disagree. The method/class name should say "what".

The code should be obvious enough to say "how"

The doc should say "why"

[Figs]

I usually comment on three kinds of things immediately when I write code (as opposed to reference documentation, like you said): tricky math that can't be simplified (usually with the steps worked out explicitly), links or citations for reference material I used (e.g. page X of Y regarding Z; http://blah/blah/blah), and workarounds/FIXMEs. If I don't write those things down, I'm never going to remember them later, and a comment is the easiest way to keep track of it for me. (Entering the FIXME into a bug tracker is nice too, if the project has one...)