Making Some Comments

I just read a good one about comments, feel free to weigh in. Here is what I had to say about it in the comments section of that blog (with extra formatting here):

Some sniglets for you:

• Obso-doc: Comment detailing what the code did last year.
• Redundo-doc: Comment literally describing source code statement(s).
• Histo-doc: Ever-increasing comment section detailing revision history, typically duplicating information in Revision Control.
• Igno-doc: Comment revealing author's lack-of-understanding of necessary algorithms, alternate syntax, etc.

Personally, I believe in minimal commenting in-code (doesn't count "Javadoc" documentation, which I don't consider comments) only to warn subsequent visitors (like me during maintenance) about certain code sections that are arranged a certain "atypical" way on purpose, i.e. to workaround something somewhere else. I prefix these with "IST" for Important Safety Tip! This heads off the "What the F*** was he doing here?" impulse to just rip it out and re-do it the "right" way.

Continuing on, I also hate:

• Identi-doc: Author "marks" every modification with their initials and the date, especially if files are in Revision Control.

I can't tell you how much all of the above comment "styles" are just noise for everyone to slog through! You are not helping anyone by inflating the size of every file with your initials/date or whatever other meaningless information you think you are providing.

Code is more information than comments, if you treat it like a writing assignment, and not like some secret only you can understand. Start by using meaningful names. I don't want to hear about how you can't type; this is your fucking job, you better be good at typing, since using a computer to write software is typing. Meaningful doesn't necessarily mean verbose. Meaningful names are hard to come up with on the first (or second or third) try; that is not an excuse to give it a pass, it is an excuse to use the Rename Refactoring when you come up with a better name!

And one more pet peeve: absolutely never use single-character variable names! Do you know how many times i appears in a file? If you are using if statements and while loops, then there's a big fat fuckload! These are used mostly as looping indices, and we have a simple fix: append an x onto it, so now i becomes ix.

Look!!! Now I can find the fucking thing pretty simply, without visiting every last control structure in my algorithm. Plus, it has x in it, to remind you that it is an index! That's a big payback from one character!

Also don't confuse comments with documentation, which these days is usually maintained within the source code files in some special comment format. If you want to tell nice stories, this is the place to do it, because people using your code will be reading this, and not your Add 1 to I bullshit.