Why should we developers bother to Comment our Code!!

Commenting your code is like cleaning your bathroom—you never want to do it, but it really does create a more pleasant experience for you and your guests. Because I’ve recently adopted a new mantra to use comments frequently and appropriately in my code, I spent a few hours researching the literature on commenting readability, reusability, and guidelines.

It was a bit overwhelming to see the sheer amount of information and discussions on the topic. Basically, there are a lot of tough, but fundamental questions out there like what does “frequently and appropriately” mean? Because there are a million different beliefs and contradictions on the subject, I created this brief overview to present my findings.

Types of Comments

Code Commenting - This refers to writing descriptive variable names that are self
explanatory. This is a minimalist form of commenting.

Inline Commenting - Specifically, these types of comments come at the end of a line of code, but we can also use this term to refer to comments inside of a function as well.

Function Commenting - This type of commenting is found on the lines above a function, and reveals all of the necessary details about that function. This includes parameters, return values, and any logic quirks or decisions that were made.

Class / Page Commenting - Comments that refer to an entire page or top level object fall into this category. Usually these comments include a broad overview, last edit date, associated files, author, and contact information. Additionally, this may include a general footer at the bottom of every page. Kevin wrote some great templates for building these types of comments in his feature on using XHTML templates.

Here are the most powerful links which should make you appreciate the usefullness of commenting in codes.

http://particletree.com/features/successful-strategies-for-commenting-code/

Art of Programming
http://www.icsharpcode.net/TechNotes/Commenting20020413.pdf

The Art of Code Documentation
http://www.gamedev.net/reference/programming/features/codedoc/page5.asp

10 Essential Development practices
http://www.perl.com/lpt/a/2005/07/14/bestpractices.html

Using Comments Effectively
http://msdn.microsoft.com/en-us/library/aa164797.aspx

Hows and whys of commenting
http://www.cprogramming.com/tutorial/comments.html

Comments Are More Important Than Code
http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=290