Search CompSci.ca
Subscribe
Programming
On the use of comments in code
When it comes to programming, writing comments could often be as important as writing code itself. Even though the comments left in the program will be ignored upon execution, it is important to realize that the software is written to be run by computers, but understood by people. Even the most amazing code needs to be maintained or updated, and that’s when someone would need to figure out what is going on in the program. Adam McKerlie points out that commenting one’s code comes close to an art form.
No matter what other people say, commenting source code is an art form. It takes finesse (and sometimes an English degree
) to properly comment your code.
The two main camps seem to be too much commenting vs. not enough. Some students understand their own code, so write very little to no comments. Others fall to the opposite extreme and comment everything they write.
// z is the sum of x and y
z = x + y;
I think that both sides are completely missing the point. This might or might not be the teacher’s fault in explaining the concept behind the use of comments in code. The single most important point I would like to establish here is: comment to explain why you’re doing something, not what.
The what part could often be easily understood from the code itself. Some programming languages, such as Ruby, are very clean and easy to read. Well structured code could often be described as self-documenting. Some might use this as an excuse to not write any comments at all – it’s easy to see what z = x + y; line does. Though returning to that example above, we still don’t know why it is so.
The benefits of well written comments come from better understanding of the program. Comments help teachers evaluate your code. Comments help peers to help you out with your code. Writing out the why part will often help you figure out how to better approach the what.
So tell me, why are you writing this method / function / line of code?
Read more
Discussion
Post a comment
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
Commenting can be good if you have collabrative project.Some people find it annoying,but it is good idea to comment your code if you’ve opensource program or library.Like your article,keep it up.
Note: BTW thanks for commenting on onecore.net Sorry i left out GCC i have used it but missed it somehow.anyway keep commenting.
Reply to comment
“The single most important point I would like to establish here is: comment to explain why you’re doing something, not what.”
Excellent point. Commenting code for the sake of commenting is useless. A competent programmer will see your code and understand what it does. Comments like “// z is the sum of x and y” will just bog down your code and make it cumbersome for the reader.
When you put in comments explaining why you’re doing something it’s a lot more helpful for the person reading it. If you have a block of code that might not make sense as to why you’re doing it an insightful comment will definitely help.
I know at Guelph we got marked for our comments. The problem was that generally the more comments you had the higher the marks (the TA’s weren’t looking at the quality of comments). I know a few people that just commented everything and got marked well.
Great article Tony and thanks for the mention
Reply to comment
I had a professor who would say: “A program is a sequence of instructions AND COMMENTS”. He was taking it extreme. He was wiring method names that take the whole whiteboar. Methods like:
GetTheSquareRootOfXAndReturnTheValueInY… he would go on!
He was nuts. I used to write comments above each method, each code block, plus a Readme file and still not get full mark for commenting the code!!! I think he wanted something like // Z is the sum of X & Y
Comments are indispensable, but usually are ignored in the real world applications I’ve seen. Not to mention no documentation.
Reply to comment
@onecore – comments have their place in personal projects as well. When you come back to your own code next month, or even tomorrow, you might not be in the same programming mind set. You will probably be able to figure out your own code, but comments would serve as excellent reminders of what you were actually thinking when you wrote that code in the first place.
@Adam – no problem, you were an inspiration for this article
So far, at Waterloo, I was fairly lucky with my TAs. I would generally just write a few insightful “why” comments, and clarify any non-trivial code (such as complex pointer operations for example) and get my marks. I think we need a better grading system here – maybe like 5% for code presentation? Things like good use of whitespace and comments.
@Bashar – that is certainly excessive. Perhaps because of the wrong idea that such professors teach, comments are the first thing to be cut out of programming projects behind a deadline. It’s not that they are ignored in the real world, but comments carry a future centric value – that is, they are mostly beneficial when someone reads them in the future.
Reply to comment
Also, by the way, some people tend to think that by not commenting their code, they remain valuable asset to the company. and in some cases, they really become so like this.
Reply to comment
I’ve long been a supporter of good commenting … I agree that it is like an art form.
I want to mention something I’ve read in two books by Cay Horstmann, Big Java and Big C . The author suggests writing method comments and blocks first, then impementing them. For example, a number class in Java:
/**
* Class that represents a number.
*/
public class Number
{
/**
* Creates a new number from a double value
* @param num double number to create number from
*/
public Number()
{
}
/**
* Add this number to another.
* @param num number to add
* @return a new number that is the sum of this on and the argument
*/
public Number add(Number num)
{
}
}
In this way the interface of the methods are the same, and the implementation can follow through.
Reply to comment
Aziz: I used to do that plus the readme file and get 8/10 for commenting
But it’s really the best way I found.
Reply to comment
/**
* Class that represents a number.
*/
public class Number
{
…
}
‘class Number’, represents a number? NO WAY!
/sarcasm
That’s the kind of comment that is useless.
Reply to comment
Aziz – OJ is right.
This is clearly redundant. If you are writing comments in style that Bashar’s “// Z is the sum of X & Y” professor is looking for, it should be a red flag.
Maybe it’s just more difficult to write meaningful comments for such a generic example. It’s easy to understand that class Number represents a “number”, without explanation. Though I still don’t get why we have to represent it in the first place. Where is it used? Why is it implemented this certain way? Are there any special caveats or edge cases that should be pointed out? I think the latter is an especially useful type of a comment.
Reply to comment
But, OJ, don’t you know? Everything must be commented.
Reply to comment
I was going to mention this but was too lazy. I couldn’t be bothered to come up with good examples. I was describing the way a book said to layout method blocks and comments before the code.
And I include redundant comments like that in code for building javadocs
. When I comment at all.
Reply to comment
Aziz: This was the point I wanted to point but got lazy also.
Tony: Those comments would be useful when you build the RoR docs.
Reply to comment
Guys, you should be less lazy when it comes to comments.
I can’t comment on the usefulness of such docs with seemingly redundant descriptions – I’ve never had to build them. Now, since this blog focuses more on the education level programming, I’m going to maintain my original point – tell me why you are coding a certain way!
Reply to comment
Lazy in the sense I didn’t want to find a good example to post, I was merely bringing up the style of outlining methods and their purpose (using comments) before writing the actual code.
I personally program in java, and thoroughly comment for javadoc. An “add()” method in a Fraction class may have a description of merely “adds two Fraction objects”, but can have more detailed notes such as whether or not the resulting Fraction is reduced or how it handles certain input.
Inside code blocks such as methods where javadoc isn’t generated, I highly support self-documenting code. code such as z = x y is self-explanatory in what it does, but perhaps not why. I agree that a comment “z is sum of x and y” is in most cases redundant, but a comment of “adding the x and y values produces this object’s z value because of their Freudian relationship” (fake) or something similar.
Reply to comment
Spot on Aziz, you redeemed yourself!
Reply to comment
If you are coding in a commercial setting, someone will be maintaining your code down the road. Make it easy on them and leave good comments.
Reply to comment
If ever you do find that you are leaving comments explaining what you are doing instead of why it is a good sign that the code needs refactoring. In fact, this is one of the no. 1 reasons I have found for refactoring code. When some programmer leaves a comment like “The following line returns the value on the top of the stack and then decrements the stack counter but only if the stack isn’t emtpy”, I immediately get the chills. This is about 6 different concerns and should be split up.
I have also become a big fan of long method and field names which lead to so-called “self-describing code”. If you do this then y = x z becomes weekly_salary = normal_weekly_salary this_weeks_bonus and you won’t need comments except where you explain an algorithm or a programmer decision to do things a certain way. It also is a good indicator for when thinsg should be split up. A method which takes an open file handle and is called calculate_sales_order_and_print_receipt_and_close_file looks silly and is primed for refactoring.
Big Hint of the day: You win more points in the field for maintainability over efficiency or cleverness. It is a hard lesson to take in but one well worth noting.
Reply to comment
Good point Mike, especially the last one! Todays hardware is fast, cheap, and scales easily – it is much better to have robust code that is easy to understand and maintain, than very clever code that runs faster because of some hack.
Reply to comment