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).

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)!