On Code Commenting!

Tanmay Vora
Posted on

Commenting of source code is one of the most ignored software development activity. Although a very important part of coding process, developers often think they can do away without writing comments.

Missing code comments is one of the common findings of code review sessions being done across organizations.

I have seen people who write:

  1. Useless comments e.g. For a function named InsertData(), the comment written is “This function inserts data into the database” when the function name explains the same!
  2. Redundant comments like name of the class file, date created, date modified, modification details etc. – something that version control tool can do with much ease. The worst part is that once written, these comments are almost never updated!
  3. Lenghthy comments which has more number of lines than the function being commented. Each and every instruction/code line is meticulously explained. This again becomes worse when descriptions are not updated.

So how much commenting is good? While there is no quantification of how much is good, only I can say is that the code comments should be reasonable and updated. Anything that genuinely describes something that is otherwise non-decipherable (like critical database transactions, complex algorithms etc.) is a good comment.

I have heard some programmers stating that if they focus on commenting, they loose the flow of coding and thought process. I suggest that developers can complete a functional class and take up commenting as a separate task (soon after the completion till the implementation details are fresh in mind).

Commenting may take up some time – but not as much as you/client might have to spend understanding a piece of code few months down the line!

Also Read:

  1. Comments on Comments on Comments at Developer Magazine
  2. In Praise of the Lowly Comment at Developer Magazine
Previous post
Power of Positive Reinforcement
Next post
Lessons in project quality

2 Comments

Alastair Revell September 1, 2007

I would agree with much of what you have said, although I firmly believe that (good) commenting should be undertaken at the same time as writing the source code. I advocate “bannering” (ie: the separation of functions using boilerplate comment headers) to help make the process of commenting almost second nature. A key element of these banners is the “Purpose” section, which states exactly what the routine in question is meant to achieve.

Tanmay Vora September 3, 2007

Alastair – thanks for commenting and I agree that code commenting has to be a parallel activity with coding however a lot of programmers I have seen are not too keen on commenting.

I like your idea of “bannering” code with respective comments. The best way I have used to do this in .NET is to write a macro function which, when executed, extracts the name of author from a variable, extracts the function name, parameters etc. in XML format and generates an SML banner with the tag empty, where a programmer can put in the relevant comments. This is not only fast but also time saving.

These XML comments can then be read by any documentation generation tool (like NDoc or JavaDoc) to generate code documentation in CHM format.