Home Email / About RSS feed

Make your Comments Stand Out

I was just going through a blog feed for Sun peeps and noticed an interesting post titled Make Your Comments Count! by Tor Norbye. His point was that modern IDE’s tend to hide comments and make the code the most important thing on screen, which is very true. However he noticed a colleague had changed it so his comments stood out, the reason being, he said, is because they’re vital.

I totally agree, comments are incredibly important, but I would have thought that was obvious? For years I’ve used a Delphi colour setting of Twilight which is a black background with white / cyan text. By default comments are in (dark) green which don’t stand out, so I change them to lime green so I can’t miss them then! A chap at work has similar settings to Tor with his comments in red (but with a grey instead of white background).

CodeWithComments

Not a particularly good example, but it shows how I highlight comments

I used to work with someone who said he didn’t need comments because he wrote “Self Documenting Code” (SDC). If by that he meant incomprehensible crap then full marks! Thing is, there is no such thing as SDC. Comments should be liberally sprinkled about and, this is the key point, be relevant.

If you going back into something (and you will) the comments help to get you up to speed. It is much quicker to read plain English than to decipher the code. Obviously you can determine what the code is doing, but that heads up in the comments is a real help.

I suppose the reason why Mr. SDC never commented is code was because he only every tended to work on stuff he’d written and when he was happy with it, “ownership” would be given to someone else (muggins and others) who would then have to fix any bugs in it (and put comments in)!

Gom Jabbar said,

February 12, 2006 @ 2:28 pm

I do think that comments help a lot, even when working with your own code. Just don’t touch a piece of code you haven’t commented for several weeks or month and then have another look at it… Instant fun!

About comments in the posted screenshot though: Do you really think it’s necessary to add a comment like “// close service handle” when it’s only a comment to the function “CloseServiceHandle();” in the next line?

You can make a mess of your code using comments, too. Sometimes it’s better to use meaningful names for functions and variables and forget about comments.

Pauk said,

February 12, 2006 @ 2:47 pm

I agree, personally, that sort of commenting is overkill. Thats why I said it was a bad example, its actually someone elses code that I’ve just reindented, but was obvious enough to show the comment highlighting.

I think thats what Mr. SDC was getting at, but he never gave his variables, functions, procedures etc obvious names. He liked x, a, i, j or others usually with vowels missing.

As for commenting your own code, I think thats essential too. You usually have to go back at some point to fix bugs or extend it, so comments are always useful.

RSS feed for comments on this post · TrackBack URI

Leave a Comment