More on Code Comments

I have written many times before about code comments. I recently read Mike Clark’s article titled Write Sweet-Smelling Comments. Just as before, I disagree with a goodly chunk of what he writes. (If you want to read some excellent tips on code comments, I recommend Code Complete, Second Edition.)

Since I could ramble on for hours about what I don’t like about Mr. Clark’s article, I’ll limit it to just his “eye-popping comments”. He got the “eye-popping” part right since my eyes bugged out of my head and I nearly puked on my keyboard.

You may be tempted to remove the read lock here, but don't because...

This can be “refactored” simply to be “This read lock …” where suitable “what”‘s and (most importantly) “why”‘s are stated.

The following code needs to be refactored, and I'm embarrassed
to call it my own.  However, we must ship this code now!  I promise
to clean it up before anyone starts thinking smelly code is acceptable.

For the love of all that is good and pure in this world, don’t write editorials in code. To be more succinct as to why this is so downright bad:

  • Who is “I”, “we”, and “my”? Writing comments in the first person is just plain wrong. After the code is checked in and is pertubated for a while, there is no effective way to know who “I”, “me”, and “my” are! So don’t use them. If there’s a reason to include someone’s name in a comment then base it on the author field or use initials or something so that if someone reads the comment in one week or one year, they know what’s going on.
  • It’s one thing to state that “The following code needs to be refactored” and it’s quite another to state why the code needs to be refactored. All of the time wasted editorializing could have been more fruitfully spent quickly bulleting out the “smelly” points and possible resolution steps. The scariest thing to see in code is a comment that says “Refactor!” followed by perfectly sane looking code that works. Why should the code be refactored? Has it been duplicated? Are there bad practices in use?
  • When is “now”? The moment after the code is checked in, relative times (just like using the first person) lose their context.
  • Don’t editorialize in comments. We have blogs now. Save it for a nice blog entry.
  • In case I missed mentioning it earlier, don’t editorialize in comments.

So that I don’t appear to be a “Negative Nelly”, I will say that Mr. Clark’s “Use of a published algorithm” is an excellent comment that I wish that more developers would use. I’ll broaden that statement further to say that I wish that more developers would research the algorithms that they use. I can’t even count any more the number of times that I’ve come across home grown algorithms that have left me scratching my heading questioning if the developer didn’t know there are fairly standard ways of implementing a piece of functionality or they were just winging it.

So as not to ramble incessantly about bad comments I will close this entry by kindly reminding developers that the code is really all that they have to show for in their life’s work (Yes, yes. The finished product. We’ll talk about that some other time.) Take some pride and show some professionalism when you write code and its associated comments.

Advertisements

2 comments

  1. Wow. Despite all the disagreements I’ve had with you in the past on things, I have to say I agree with you 100% on everything in this post. I’m actually shocked that anyone would encourage such an absurd style of commenting as the “editorial” you showed there. I’ve worked with code that has just one or two comments like that, and it’s infuriating and unhelpful. That sort of comment appears far too glib and “cute” for professional work.

  2. I told you that we disagreed less than you believe *grin*
    “Infuriating” — that is a very good description of what I feel when I read editorial comments. There is nothing worse than laboring through thousands of lines of someone’s code that looks like and works like a train wreck only to find some “cutesy” comment. It slashes my faith in the professionalism of the author and infuriates me!
    Take care!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s