Reg Developer has an interesting discussion this morning in an article by Matt Stephens: “Sweet, sweet smell of comments in code?“. The discussion talks about whether comments in code are a good thing or a bad thing. Personally, I am a fan of comments however I do believe that comments should convey a concept and not simply explain textually what is happening in the lines below.

For example here is some code that to me seems a bit pointless because it does not help explain what the code is doing:

/* Calculate 17.5% of A and store in C
c = a * 17.5%;

/* Show the value of C on the screen
println(“Value of C is: “ + c.toString());

Here is another example, this time in COBOL:

* Write the Record to the TEMP file
WRITE temp-rec.

The comments in these two examples of do not add any value to the code, however they could have been written conceptually as:

/* Calculate and show the VAT at 17.5%
VAT = Price * 17.5%;
println(“Value of VAT is: “ + VAT.toString());

and

* Temporarily store the stock record until the transaction is complete
WRITE temp-rec.

Comments are important because as time passes it may not always be immediately obvious what a section of code is or how it relates to the program as a whole. Also, other developers may work on sections of the code and may make assumptions if the concept of a section of code is not explained clearly. Obviously not all code requires comments and I believe there is little point in commenting for the sake of commenting – any comment must always add value to the code in the same way that a good image adds value to words.

Other factors for good commenting are to use meaningful variable names and method names that provide some indication as to their purpose. Complex calculations should always be commented with clear explanation as to what the calculation is used for – it may make sense at the time but a month later or to someone else it may not be as obvious. Using comments to break up logical sections of a code to make it more readable is also useful as reading a long list of code can be difficult to follow. Breaking long pieces of code down into smaller more manageable (and more comment-able) sections can also make the program easier to work with and allow sections of code to be re-used

Other sites that talk about code commenting include:

• Successful Strategies for Commenting Code
• Comments Are More Important Than Code
• Wiki: Comment (computer programming)
• Code Tells You How, Comments Tell You Why
• How to comment Computer Programs

Technorati Tags: code, comments, program, software, development