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.