Mistaeks I Hav Made

What and Why

I've used, or been forced to use, many different commenting conventions over the years. The most awkward was a coding standard that required big banners at the top of each source file and a header comment for each function that repeated the information that was in the function's signature and followed it with a description of the function's behaviour that usually ended up pointlessly rephrasing the function's name. Another awkward commenting convention I've had to use is Javadoc : source code can become quite unreadable when it contains long comments that contain HTML markup.

A common misconception of agile software methods is that they eschew comments completely. On the contrary, like everything, it's a matter of context and sometimes comments are necessary. Agile methods try to use meaningful identifiers as much as possible to reduce comment noise and to ensure that human readable text is always kept up to date. In my projects, I have come to use a commenting practice that can be summed up by a pithy one-liner that Joe suggested I post here:

Identifiers say what. Comments say why.

Code is usually straightforward enough to require no more commentary than the identifiers provide. However, when I have to make an unusual design decision, I add a comment explaining why I have done what I have done.