Suramya's Blog : Welcome to my crazy life…

June 13, 2012

Should you comment your code?

Filed under: My Thoughts,Tech Related — Suramya @ 11:12 PM

Had a really interesting discussion at work today about putting comments in source code. A while ago someone I know told people not to put comments in any code they create and we were arguing the pro’s and con’s of this. I personally think that good comments are quite useful and should always be added to code, but there is another school of thought that says that code should be written well enough that comments are not required. When I started coding, I was told to always put good comments in the code because it helps the person who is reviewing/debugging your code when you are not around to understand what your logic or thought process was when you created that wonderful collection of code. Assuming that your code is good enough to not require any comments is very egostical. What is perfectly clear and logical to you because you have been working on a system for a couple of years will not be clear to someone who is new to the system. Put another way, code tells you how something is done and comments tell you why.

I have had the joy of maintaining legacy code written in a mix of VB, VB.NET and Javascript with 0 comments in the code. Believe me it was not fun. The best part is when I talked to the guy who had written the code he could understand it perfectly without needing comments.

I am not talking about putting comments like “Here we are checking if the value of Var is more than 5” for code that reads: if($Var > 5). I am talking about taking a few lines to explain code like (This is an example from one of my scripts to create collages):

	# Repeating the cropping process to get the other half of the image. This reduces the possibility of half empty collages

	for ($i=5; $i>0;$i--) 
	{
		opendir(DIR, ".");
		while ($file=readdir(DIR)) 
		{

I could figure out what this 30 line blob of code was doing after walking through the code in 5-10 mins or I can read the comment and understand the logic in 30 sec’s. If needed I can then look at the code more closely but if I just want to understand how the code works on a high level comments help a lot.

Now lets look at it from the other perspective. Comments take up space in the file and if not well written they just take space and at times if they are not updated when the code changes can provide the user with incorrect information. The idea is that if required any documentation on the code can be auto generated by auto documentation tools. However if my developers are not trustworthy/reliable enough to update comments in code then I am pretty sure they can’t be trusted to follow the format required for the documentation creator software either.

The one point that made sense to me was that at times people put information in code comments that should not be public. For example a developer can comment out a section of JSP code that has the DB connection info for the dev servers but now this information is visible to anyone who views the html code generated. Or other notes/comments that probably should not be openly accessible to everyone that searches.

Last point before I end the post. Code should be clean and readable, you shouldn’t rely on comments to cover for bad coding practices. But I don’t want you to put a comment on every line of code, you should only put useful comments. Comments that help a future coder understand why you did something in a certain way are great.

What do you think? Code comments are good? Bad? You don’t really care?

Additional articles/posts that discuss this:

* Coding horror
* Successful Strategies For Commenting Code
* Don’t comment your code

This is all for now. Will post more later.

– Suramya

3 Comments »

  1. I started adding comments for my future self. I can never understand my thought process the night before otherwise

    Comment by Malcolm — July 3, 2012 @ 11:40 AM

  2. Same here, I started commenting my code for pretty much the same reason initially.

    One example I remember that made me really aware of the importance of commenting code was a DOS prompt clone I had written which would work normally (pass all commands to DOS normally for execution) for the most part but every one in a while it would start returning funny results. It worked great and I tired using it after a while, but couldn’t remember the secret key combination that would terminate the program, went through the code and it was a ASCII code for a key combination. Spent about an hour trying to remember what keystroke had that code. Finally ended up replacing it with another combination.

    After that I made it a point to always comment my code.

    – Suramya

    Comment by Suramya — July 4, 2012 @ 9:27 PM

  3. […] Should you comment your code? […]

    Pingback by Blog Review: Should I comment code? | Lexical Scope — November 21, 2012 @ 9:43 PM

RSS feed for comments on this post. TrackBack URL

Leave a comment

Powered by WordPress