On Code Commenting!

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