Commenting Code

October 30, 2008 at 8:15 PM — Ben

Do you add enough comments to your code?  Too many, perhaps?  The last few months, I've realized how helpful comments in source code can be.  Years ago, I wasn't a big comment guy.  I think I didn't want to spend the time commenting and felt like if I (or someone else) looked at the code for a couple of minutes, they would understand what's going on.  This is basically true, but comments remove or reduce the need to spend those few minutes studying the code to see what's going on.  When maintaining code, you still need to understand the code before making any changes, but spending 30 seconds, a minute or even a few minutes to add comments when you're writing code and everything is fresh in your mind is really proving to be beneficial when going back over code in the future.

There's also times when there are no comments and after spending a few minutes reacquainting myself with some code, I'm still not 100% sure if I fully grasp why something was done a certain way.  Comments are priceless for these cases too.

The other thing I've started doing as well is including a date with my comments (including the year!).  It all may seem unnecessary and a waste of time when writing code, but more times than not, pays off in the future.

Posted in: Development

Tags:

Permalink | Comments (2)

Comments (2) -

Henrik Stenbæk
Henrik Stenbæk says:



Yah comments are great. But remember to stay calm when writing your comments, one never know where your source code will end: it could be mailed to a subcontractor for future development or just float around on the internet (http://www.kuro5hin.org/story/2004/2/15/71552/7795).

I once was to an job interview where they told me that the way they worked was that they first write the comments:

//get all files in dir
//loop the file list
//do something
…

Then they had “code review” on the comments and after approval they write the code between the comments line. I didn’t get the job, but I took the idea about writing comments before code and use it now and then when writing complex routines

Henrik

Seth Johnson
Seth Johnson says:

Ironic, sometimes those comments are really left for your 'future self', when you revisit that code in 3 or 6 months and wonders what the hell 'past self' was thinking when they wrote that routine.

Comments are closed