Time to get better

Battered, bruised, and still smiling.

My team just finished a long, involved, and complex project.  The outcome is a milestone product that we are proud of.  In fact it is probably the best product we have released in years.

As part of any good strategy to improve, the team will be hosting a retrospective which will allow team members to discuss what practices they would like to continue to perform, and what practices need improving.  I am heading on vacation shortly and will not be available to attend, so I drafted some notes listing my humble opinions about the good, bad, and ugly practices.  It gave me a chance to reflect on the benefits of a retrospective.

It is important that teams host a retrospective shortly after a milestone, because it provides teams with many benefits, including some which may not be obvious:

• It allows team members to indirectly thank each other.  By stating that a practice was beneficial, the team member who original suggested or implemented the practice gets an emotional boost.
• The retrospective provides an opportunity for newer, shy team members to participate in larger team discussions, even if they only say ‘I agree".
• The team can focus on improving itself without the pressures of delivering a product
• It builds the community, since a retrospective involves different functional teams discussing issues in the same room

The retrospective is a beneficial activity that is not restricted to our company.  Some company executives host an annual retrospective where they discuss the prior year.  Others follow processes that require retrospectives, such as SCRUM.

If you are not performing retrospectives, you are missing out on a vital opportunity to inject successful practices in to your next project.  Start now!

Here is a good resource to get you started: Iteration and Release Retrospectives: The Natural Rhythm for Agile Measurement.

Comment Lint

How can you clutter code with comments?  Easy, add some history.

I have had the pleasure of cleaning up some more code today.  At times this task is very boring & tedious, but I know that it is necessary to improve the quality of the product.  While cleaning up I would read whatever documentation resided in the code to better understand what was going on.  While some documentation added insight & value, other documentation did not.

Take this simple method history comment:

/**  NameOfTheMethod
*
*    purpose of the method, inputs/outputs, & assumptions
*
*    date        name      description
*    ----        ----      -----------
*    21/07/07    MPower    Initial Version
*    22/07/07    SShep     Changed parameter to const
*    23/07/07    PSherman  Removed old handler 
**/

There are three entries in this history: when the method was created, and two modifications.  So I have to ask, is this type of information valuable?

Let me put it this way, how often do you have to determine when a method was created?  How often do you require to know when it was modified?  I can count a handful of times in the past few months that I needed to determine who made a modification & when it was made.  Each time I reviewed the check-in history of the file via our source repository, because I did not believe the history that was presented to me by the comments in the source code.  In some cases the only comment was the one outlining the methods initial creation, but reviewing the code lead me to believe that other modifications had taken place since then.  My distrust was well founded because the source repository listed many more modifications which were not revealed in the comments.

Comments are all about expressing useful information which exists outside of what the code itself expresses.  While comments that list the history of a software component attempt to do this, I do not find them successful.  I get a far better understanding of any changes made by comparing two revisions of a file using Araxis Merge.  In my humble opinion, comments listing historical changes are a visual eyesore & are not worth the effort.

One of the fundamental principles in software development today is the "Don’t Repeat Yourself (DRY)" principle.  DRY plainly states that you should strive to avoid duplication.  Our source repository will always provide me with accurate & up to date information, which is much more then these types of comments can promise me.  Given that the history of the code resides in two places, I continue to rely on the source repository for my information.

————–

Here is quick stab at another practice using comments:

/*---------------------------------------------------------------------------
 * FILE: ViewController.cpp // <- do we really need to state the name of the file we are already viewing?