c o d i n g f r o g s

croaking about programming, programming languages, software engineering, and the business of software

How To Ruin Your Own Vacation

You know the feeling.  The feeling you get as you are heading home from work on the last day before your vacation.  That feeling of the weight and stress and pressure of delivering excellent software on time just floating away off your shoulders.  Nothing to look forward to for the next two weeks but fun and relaxation.

Right?

Or are you worried you are going to get a call?

It's the nature of the beast.  We plan to escape, but sometimes that call just can't be avoided.

Sometimes it can, though.  Sometimes you get called because you did something boneheaded, something you could have avoided that would have made your vacation more like, uh, a real vacation.

Some time ago I was working through a bug that was assigned to me at work.  After a bit of digging, I realized the bug was being caused because two methods in a related class had recently been deleted.  Putting those methods back in the class would fix my bug, but was that the right thing to do?

I assumed not.  I work with smart people, so I assumed that there was a good reason for removing those methods.  So I dug into the source code control system to determine which checkin had removed those methods, who had performed the checkin, and why.

I found the commit in question, noticed who had done it, and looked into the commit notes.  Here's essentially what I saw:

Description of problem:  Code was broken.  Description of fix:  Solved problem.

Meat Loaf says "two out of three ain't bad," but that doesn't apply in this case.  Note that our checkin system automatically adds the "Description of problem" and "Description of fix" tags so the commit notes weren't nearly so verbose as it appears.

Obviously this was of no help to me in determining why the change was made, and without a reference to a bug database record I couldn't look up the bug to find out about it either.  So even though the developer in question was on vacation that day, I had to call him:  I couldn't wait for him to get back for the answer.

So, there you have it:  One way to ruin your own vacation is to avoid taking any time at all to provide useful commit notes.

Notice that even typing the notes that were put into this commit was an utter waste of time.  I don't know about you, but I don't make a habit of checking in fixes to code that isn't broken.  So the statement "Code was broken" is a statement of the obvious.  Of course the code is broken; why else would you be checking in a fix?  Saying the code was broken is redundant and unnecessary.  Likewise for "Solved problem"; why would you be checking in if you didn't solve the problem?

The single most effective change that could be made here would be to simply reference the bug database record.  Even if the problem description were simply changed to say "Bug #3165150" that would be enough.  Annoying, but enough.  With that I could at least look up the bug in the bug database and maybe figure out why the change was required.  But seriously, how long does it really take to add a few notes about what changed and, more importantly, why?

I've also seen commit notes like this:

- removed GetLastWidgetStatus() method

- modified signature for UpdateWidget()

- added null check to SyncWidget()

Gosh, really?  You needed to tell me that?  I thought that's what diff tools were for.

Here's my suggestion for creating Awesome and Useful commit notes:

• Include a description of the problem.  Use the title from the bug record as a guideline.  You might want to be a little more verbose, but often it isn't necessary, as long as you...
• Include a reference to the bug record.  A clickable link is best, if possible; if not, at least a record ID so the bug can easily be found.
  • At this point some of you may be saying, "What if there is no associated bug record?"  In that case, the answer is, "WHY ON EARTH ARE YOU DOING WORK WITHOUT AN ASSOCIATED BUG RECORD?!?"
    • I mean, seriously.  If for no other reason, you need a record so your boss knows what you are doing!
  • Horrible Example:  "Code was broken."
  • Bad Example:  "WidgetManager class not working."
  • Good Example"  "WidgetManager not correctly updating widgets on DisplayChanged event; see bug #5150316."
• Include a description of why you made the changes you made, not just THAT you made changes or a simple enumeration of the changes.
  • Horrible Example:  "Fixed code."
  • Bad Example:  "removed GetLastWidgetStatus(), modified signature for UpdateWidget(), added null check to SyncWidget()"
  • Good Example:  "The UpdateWidget() method had no knowledge of the event causing the call so it wasn't handling the DisplayChanged event properly; I added a parameter to UpdateWidget() to provide this information which allows us to handle the event correctly.  Also added a null check to SyncWidget() which would have caught the bug.  Removed GetLastWidgetStatus(); nobody is calling it anymore."

See?  That's not so bad.  Just a few minutes out of your life to show your love and caring to your team members when you are gone.  Just a few minutes out of your life so you can really enjoy that vacation without worrying whether the phone is going to ring.