« Markdown Parsing
Using Custom Attributes for Fun and Profit »


Is your code your commentary?

I believe that you can tell the experience of a developer fairly quickly from their commenting habits.

Going by my completely made up chart, my experience has been that initially developers do not comment much at all, but as they progress they switch to over-commenting before eventually learning how to comment appropriately.

Part of the reason for this is from university education and being forced to explain your work with heavy commenting.

However, developers will learn that an incorrect comment is worse than no comment at all.

My philosophy is that there is only one place comments belong, and that is the XML Comment (Or JavaDoc, DocString, etc depending on your language of choice) that provides information about each method.

These comments do not explain your code. They explain your interface, and are much more useful to an experienced developer, especially with the modern IDE's of today (Visual Studio, Eclipse, NetBeans etc) that can read these comments and provide documentation on the fly.

I create these religiously, even for private methods.

The code in your methods should act as a commentary on itself. If you need a comment to explain what it does, then I would consider breaking it out into multiple methods until the code is clearly understandable.

The need to comment code often indicates unneeded complexity.

Of course, you cannot always adhere to this, and there are occasions where I have to comment an obtuse line, usually because I am using an already obtuse 3rd party API...However, I try to avoid this if at all possible.

Or, you might have a single line of code that describes a complex mathematical equation, and you might want to stop and explain the purpose behind it, a comment is appropriate there.

So, before you write your next comment, stop and think about how the code might be cleaned up to make its intent more obvious.

You will end up with cleaner code, with less noise between the lines and anyone who has to work on your code later will thank you.

Posted by Jonathan Holland on 2/4/2009.

Tags: Comments   Opinion

Comments:

No, no, no. Amount of comments is irrelevant. Quality of comments is paramount.

Comments are not there to explain what your code does. That should be self evident from your function and variable names, and from clear and simple code.

The purpose of comments is to explain why your code does something that might be seen to be unexpected a year from now.

If you have to modify an SQL statement to work around a bug in some DB package you're using, a comment like: "This SQL statement now sorts by field A first" is totally useless.

A comment, on the other hand, that says something like "Sort by A first to work around bug in FooDB v0.2 that causes a rare crash when sorting by B first." is vital. As in, "you leave this out and you damn well better be laughed out of the code review".

Gravatar Posted by hacksoncode on 2/4/2009.

@HacksOnCode

I disagree, that bugfix and other tracking comments are the reason for bug tracking and source control comments...Not code comments.

The appropriate place to say "Sort By A first to Fix FooDB" would be during your code commit. If anyone has a question regarding why that was done, they can look at the revision history, go see your comment, and then ask you what you did.

SCM tools exist for this reason, it would be wise to use them.

Gravatar Posted by Jonathan Holland on 2/4/2009.

Even if you consider my example to be unfortunate (though I will say that, while theoretically possible, no developer I've ever worked with actually goes and does that operation you're suggesting when they're looking at code and trying to understand/maintain it, resulting in really bad regressions that may take a long time to track down), the point still stands.

Replace that example with something more along the lines of: "we're using a hash table here due to an analysis that indicated a balanced tree would be insufficiently performant (see documentation )" instead of "look up the value in a hash table" (or even just code that does that).

In some cases, that kind of stuff belongs in design documents (though c.f. by comment above, amplified by 10), but without an actual code example it's hard to articulate an example that you couldn't poke holes in.

Gravatar Posted by hacksoncode on 2/4/2009.

hacksoncode got it right. Why on earth would you want someone to have to dig through subversion commit logs in order to understand a critical part of the code. Often these sections of code are not even obvious without that comment.

Stuff like

// IMPORTANT! This next line looks redundant, but it's very important because...

are one of the most important reasons for comments. If you have to document your interfaces, you're not doing a good enough job of naming your variables, methods, and classes.

Gravatar Posted by Tim on 2/4/2009.

Bleh. Not sure what kind of code you have worked with but generally only commenting to explain the interface does not help a developer when trying to refactor or expand an existing method. There have been several instances when refactoring math heavy code that I have wished the previous developer would have commented the code with the reasons that he had approached the problem the way he did. The math was easy enough to dissect, but it was pretty much impossible to figure out why he was doing what he was going. Bad comments echo what is already written on the line of code. Good comments explain why.

Exmaple: (BAD)

int a, b, c; c = sqrt(a^2 + b^2); // get sqrt of a sqrd plus b sqrd

Example: (GOOD)

int a, b, c; c = sqrt(a^2 + b^2); // use pathagorean thrm to get len

Don't assume that developers that work on the code after you think in the same way or can read your mind from you code.

Gravatar Posted by bleh on 2/4/2009.

To be fair to Jonathon, I will say that I've often rued the inadequacy of current source code annotation tools. It sure would be nicer if that comment about the bug just showed up as a highlighted footnote in the source code so that it doesn't get in the way of reading and understanding the code the rest of the time.

A sufficiently integrated tool could make checkin comments (etc.) an adequate way of documenting this stuff. I've just never seen a tool that a) did this well enough to be useful and safe, and b) I could be sure was going to stay compatible with all the other tools I use and remain supported for the lifetime of my code (which often has meant >15 years for code I've worked on). Oh, and which didn't cost an arm and a leg.

Gravatar Posted by hacksoncode on 2/4/2009.

hacksoncode is right here. The KEY THING that a comment should do is explain WHY not HOW. Also it is unreasonable to bury the why explanation for code in the commit logs. The XML comments to "explain your interface" is just fine if you are creating an API for developers to use externally, otherwise it's much more important to explain why a piece of code is being written.

Gravatar Posted by terry on 2/4/2009.

Comments are closed on this post.