Subscribe to Rahul's Blog        RSS Feed

Overcommenting or Undercommenting?

Icon 2 Comments
Writing comments and in what quantity has always been a point of debate with the coding community. Everyone has a different style of commenting and everyone does it in different volumes. However when I was reading Six ways to write more comprehensible code (a must read) at the IBM developerWorks site, it got me thinking about what I comment and how do I do it.

Mostly, when I make small scripts or programs for myself, I usually don't comment much if at all. But this approach seems ok to me since the lines of code do not usually extend over 25, and I rarely code *just for myself*. However when I code for my job or an open source project I am involved in, I usually take a more thorough approach. For example, I code in Ruby now-a-days. Right at the beginning of the script I write the project name, when did I start writing it, what is its purpose and finally major updates with their dates.

XYZ Project to change the world
Testing script

Author: Rahul Batra
Date(start): 27th April 2007

30th Arpil 2007: Added popup configuration

2nd May 2007: Valid data reading capabilities

4th May 2007: First working script complete with MySQL data output

7th May 2007: Added getting login URL from MySQL table instead of being hard-coded
					 Made number of rows per page variable for genericity
9th May 2007: Added variable no of coloumn support
					  First generic script completed 

5th June 2007: Added support for disabling auto-refresh

From this moment on, I write the purpose of a block of code just above the block and make sure I leave a blank line or two between two logical blocks of code. Of course I also write some useful explanation for lines which are slightly tough to understand in the first go.

#Regex used for getting the total number of rows on the server
<code here>

#Possible optimization could be to reduce sleep() parameter
sleep 5

If you are a beginner into coding, I hope this serves as a good (though terse and incomplete) reference on how-to comment your code. If you already have experience and a style of commenting, share your views in the comments. I'd like to learn more effective and more clear commenting styles.

2 Comments On This Entry

Page 1 of 1

salibhai Icon

06 June 2007 - 03:01 PM
I like to make my function names and my code "self documenting", i.e. as clear as possible. I do this by making the names longer and more clear

for example

if (isSold(property) && userName != null) ....

also, for function names i will use long descriptive names such as:


dragon-slayer Icon

07 June 2007 - 09:34 AM
Interesting,I like your adding the updates to the comments suggestion I might start doing that.Im going to get into the habit of clearly commenting my code.
Page 1 of 1

Trackbacks for this entry [ Trackback URL ]

There are no Trackbacks for this entry

Search My Blog

0 user(s) viewing

0 Guests
0 member(s)
0 anonymous member(s)