Code Commenting: Just How Important is it?

This week I have decided to discuss one thing I have found to be extremely useful while coding: comments. In the past, I have been made fun of for what my peers call “excessive commenting.” While the amount of comments in my work may easily be considered “excessive”, I am never the coder scrambling to find a certain piece of code when something goes wrong. With this in mind, let’s take a look at the pros of commenting as well as some good practices when it comes to comments.

The obvious benefits of commenting are mostly organizational. Why spend hours sifting through code looking for a single piece of text when one can simply refer to their comments to find out where that very piece of code may lie? These comments not only help the author, but anyone who may need to edit the code at a later date. Finally, these comments can serve as short, simple reminders to coders who may have left the project in question unedited for long periods of time.

Just in case this post has changed the view on code comments, here are some tips for more efficient commenting. One should not go about commenting on every line or few lines of code. Comments are there to add information to pieces of code that may not be all that clear. To build upon that statement, the comments added should be clear, short and in a similar format each time. Block of text comments are more often than not simply ignored or brushed off. Finally, the tip that is possibly the most important: commenting should not be held off until the last second. The last thing anyone wants to do is read over several pages of code they just finished because they didn’t bother to add important information as they went along.

Hopefully this elaborates a little on why some programmers stress how important commenting within code can be. For more reading, you can check out these small articles on commenting tips here at DevTopics and at HongKiat.com.

Until next time, readers!

Advertisements