Using Comments

Posted 2012-10-16
Written by Matt Frost
Category code

Code comments are strange things; they can be invaluable or they can make the code they're describing more confusing. They can be necessary, unnecessary, explanatory or muddled and some times they're neither; they just are. I've heard a lot of people speak about code comments, in fact some Agile teams make commenting code part of their definition of done; not something I would do. Code comments have their place, don't get me wrong; but I don't usually come across good comments. The following is my thoughts on code comments, when to use them, how to write them and somethings that generally annoy me about them.

When NOT to use them

Code comments should be used when the code isn't easily decipherable, when I see comments that don't tell me anything new, they waste my time. For example:

// foreach loop to loop through the $states array
foreach($states as $abbrev){
....
}
That's not a good comment, I can tell by looking at the foreach loop that 1) You're using a foreach loop 2) That a foreach loop does in fact loop 3) That you've passed, what I'm assuming to be an array called states into that loop. I can actually look at the code and understand it much faster than your explanation. My feeling is that if you feel the need to explain the basic language constructs in your code comments, you probably don't hold your co-workers in very high esteem. Let the language speak for itself, if someone wants to know how a foreach loop works; php.net will do a better job of explaining it than you will.

When TO use them

If you're working on a data structure where the origin isn't obvious, or if you're working with poorly named objects, methods and properties that don't lend well to readability; it's courteous and proper to clarify it. The person that wrote the code may think that $stcptl is a perfectly clear abbreviation for State Capital, but it's not; in fact it never has been and probably never will be. If you happen to be the developer that stumbles into that and figures it out, clarify it for yourself and the next developer.

I know that YOU would NEVER use variable names like that, so I'm of course referring to these situations where you come across some other developers poorly incubated variable names. There's also the issue of unnecessary complexity; sometimes things are done in a really overly complicated way and you're not totally convinced that you can fix it right there. That's a good time to learn what you can and leave a comment there, your goal should always be to write the least amount of code that solves the problem.

Check yo'self

If you find yourself writing new code that you feel needs a better explanation, that's a really good time to stop and evaluate the approach. Should I really have a for loop nested inside another for loop inside and if inside a switch? Is there a simpler way to accomplish this? (Hint: The answer is probably yes). Taking the thought, "I need to comment this" and figuring out why can lead you down the path of writing better, maintainable code. The best comment is the one you didn't have to write, fight the urge to think that simple code is beneath you. The best developers are the ones that write easily understood code, not that overcomplicate things.

Pet Peeves

I think incremental comments are great, you don't always get to finish a block of code in one sitting and incremental comments can help you regain that thought process; just remove them when you're done. It doesn't take much to delete it, once your place has been held and you write clear, concise code that doesn't need to be comment; go ahead and just take those comments out.

Swearing in your comments has always bothered me, that may be because swearing bothers me or it may be because proving that you can drop the f-bomb in a code comment doesn't really add any value. The belligerence that often times accompanies a difficult problem only serves to frustrate the next person who looks at the code, so why not post something encouraging and actually try to get help with problem. Curse word filled, belligerent comments are selfish and detract from the goal of writing quality software. Maybe, I'm a bit of a prude in this area; so be it, I don't like it.

Keep it short, keep it focused, don't drone on and on about what you were thinking and why you were thinking it unless it's absolutely pertinent to the problem at hand. Chances are it's probably not and you're going to hide anything of actual value inside a horrifying block of inanity.

In Conclusion

The goal should always be to add value to a codebase, whether than be in the form of code, comments or documentation. Bad comments are just as bad as poorly written code and good comments can take poorly written code and make it more easily understandable. Keep in mind this is all from my perspective, you may have differing opinions in certain areas and that's perfectly fine. In my experience I've come across far more bad comments that good ones. I just want to encourage you to think before you comment and make every extra bit worth something!

Comments

Gravatar
Ventus

2012-10-16

I like to comment classes' methods and fields. This generally helps me when working with a good IDE. This way I don't need to remember the whole code and what each method's parameters are.

Comments also help in not obvious statements. E.g. when I put somewhere a preg_replace and it doesn't seems reasonable at the first glance.

Good article,
cheers

Gravatar
Andrew Mccombe

2012-10-17

What are your thoughts about phpDoc style comments preceding classes and methods? Personally I find them very useful if properly done as my IDE shows these comments as hints, helping speed up development.

Should these be discouraged?

Gravatar
Eric Hogue

2012-10-17

Good post,

I disagree with you on commenting badly named variables. You should probably rename the variable and make the comment unnecessary.

My general rule about comments is saying why something is done, not how. If you need to explain it, it's probably too complicated.

Gravatar
Marin Crnković

2012-10-19

I use comments for prototyping ( http://blog.anorgan.com/2012/04/15/comment-driven-development/) and I think having more comments than needed doesn't hurt

Gravatar
Scott Mattocks

2012-10-31

Comments aren't supposed to describe form and function. They are supposed to describe intent. It doesn't matter how clean your code is or how well named your variables are. Eventually, you will forget why the code was written the way it was and what factors went into the decision making process. If you don't understand why code is written the way it is, you can't hope to refactor or maintain that code correctly.

Posting comments after has been disabled.