Critical to that, however, is the adjective "good", as in "good comments." Writing comments can be incredibly useful, but writing *good* comments is a learned skill that requires judgement and taste.

Much ado is made nowadays about the "craft" of programming. I dislike this analogy for a number of reasons, but there's no denying that good programming has a craft element to it, and I claim that good commenting is one of the harder of the craft skills to master. In particular, there *are* good reasons NOT to comment something: the code is so obvious the comment would just be a restatement of the manifestly evident, but with the added visual clutter and cognitive load imposed by simply existing and the added maintenance burden of being kept in sync. When I see a comment, I often take it as an indication that something notable is happening: if the comment is superfluous then I'm left wondering WHY it's there and what about the code I'm missing. Similarly, comments must be maintained: my experience is that out-of-date comments that have fallen out of sync with the code are strictly a liability. Finding balance between the costs of commenting and the positive benefits of comments takes time to develop.

When I was younger, I dressed somewhat better than I do now and when I was in the Marines I once found myself in a social situation where it made sense to wear a tweed jacket. Another Marine introduced me to the concept of, "always, sometimes, never" vis which of the three buttons on the front of my jacket to button: top button always, middle button sometimes, bottom button never (whether this is good fashion advice or not is another matter). I think that something analogous is true of writing good comments:

1. A comment should never simply parrot the code:  i++;  // Increment i.

2. A comment should sometimes explain *what* the code is doing.

3. A comment should always explain *why* the code is doing what it's doing.

Note that these are specific to comments, not to code: it does not follow, for example, that a line or stanza of code should always be adorned with a comment explaining why it exists: (think, `i++;  // Increment the array index for the next iteration of the loop.` Ugh).

Btw, this is something I think that Unix did very well.

        - Dan C.