Subscribe to Rahul's Blog
2 Comments
Posted by
rahulbatra 
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.
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.
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.
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.
=begin 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 =end
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.
Share This Entry:
2 Comments On This Entry
Page 1 of 1
salibhai
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:
CreateSqlParametersAndCloseConnection(...)
for example
if (isSold(property) && userName != null) ....
also, for function names i will use long descriptive names such as:
CreateSqlParametersAndCloseConnection(...)
dragon-slayer
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 ]
|
|
| 