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.

"What tool should we use?"

How many times have we hear those words? When a group of developers is presented with that question most will scurry off and start searching the web for information. A chunk of those developers will eventually enter a spin cycle and will never report back a result. The rest of them will come back with an answer and say "Here's what we should use and why."

Move forward about a year.

• The project was successful. Everyone's happy. The team moves on to the next project.
• The project was unsuccessful (regardless of whether or not it was the "fault" of the tool or not).
• Some key developers leave the project. New developers are brought on who weren't part of the original decision process.

Now the questions are: were those original "why's" valid to the problem at hand and how do they affect projects moving forward?

In most environments the answers are easy: "we don't know". Most teams don't record the decisions made and they don't have a way to measure success at any level (save, perhaps, for the project itself).

Enter the rubric.

When the "What tool should we use?" question is first asked do this: spend an hour or so with the group and define the major business and technical requirements as they are viewed at the time and write up a rough rubric -- a set of criteria and a scale for determining relative importance of the criteria. Agile teams should be able to plow through this requirements definition by using one of the standard planning methods.

The rubric is used to ensure that each tool is evaluated in a consistent manner. It ensures that the group is all pointed in the same direction. You may have to change your rubric as you go along to meet new concerns. (Make sure that all tool candidates are rescored against the new rubric.) Once a decision is made you can be assured that the reasons for choosing that tool are known and understood.

Will a rubric ensure that you never make a bad decision? Certainly not. So why do it? Let's examine a case where a rubric is not used:

A tool is chosen by standard means (i.e. someone just picked it). The project fails. During the lessons learned meeting the following is heard:

  Manager:  "Why did we choose this tool?"
  Developer:  "I don't know.  Joe chose it."
  Manager:  "Where's Joe?"
  Developer:  "He left the project a few months back."

In many environments the blame will be placed solely on Joe. Without some way to compare against what was orginally expected of the tool, how can the success of the tool be rated? More importantly, how can you be sure that the same mistakes wont be made on the next project?

  Developer:  "We're not going to use that same tool that we used on the previous project!"
  Manager:  "Why?"
  Developer:  "Don't you remember?  That project crashed and burned!"
  Manager:  "You're right!"

It's easy to confuse the cause-and-effect reasons for the failure of a project. It may be that the tool was the reason for the project's failure or it may be that the tool was the reason for the project's success. But the root cause of the project's success or failure may be unknown since the tools were chosen in an ad hoc manner.

Had a rubric been used in the above case, the team would be able to go back and look at the requirements for the tool and how those requirements were weighted. Let's say that the project failed because the tool had a number of critical bugs that were not patched in a timely manner. Looking back at the rubric one could check to see how the product was rated in the categories of "time between releases", "relative stability and maturity", "number of outstanding bugs", etc. If none of those qualities were investigated then for the next project the team knows that they need to look at those and rate them appropriately.

Through the proper use of a rubric, the consistency and quality of projects can be systematically improved.

As a follow on to the article entitled Using OpenGL with SWT I would like to mention that I have a SWT OpenGL binding available at:

http://www.realityinteractive.com/software/oss/index.html#SWTOGL

Happy SWT and OpenGL Coding!

If you're working through some ideas, are your fleshing them out or flushing them out? Accoring to both Merriam-Webster OnLine and this blog entry, it's fleshing out.