Commenting Code

Mike Clark wrote and article on commenting code and Cedric adds a few things in The Art of Commenting, both are worth reading. I have a couple of other techniques which I find useful.

Make comments complete sentences. It takes a little longer but it helps make the context you have in your head, that the next guy will not, more explicit.

Put comments after the code to which they relate. Keeping it DRY is hard because before you write the code you are thinking about how you will achieve the result you want. How you achieve something it not, generally, useful in a comment. If I want to see how something is done I will read the code. I want comments about what the code achieves, and why achieving that is important. It is easier to comment about what has been achieved, and why, by writing the comments after the code because how you achieved it is already written. In my experience, this practice also leads to comments reading a bit like assertions, which I quite like because it make bugs stand out a bit more.