Bread crumbs in version control

I’m sorry but sometimes I really don’t get why even seasoned developers doesn’t learn the art of the commit message in version control system. All too often I’ve come across check-ins where the entire commit message just reads “bugfix”, “change”, “oops” or something just as mindless.

The effort of writing a useful message compared to the potential benefit seems to be one the best ratios - but of course the pay-back is usually some time away - too bad. Once you work on the same code for years - or even better inherit code from others, you’ll quickly learn to appreciate anyone who used more than 10 seconds on composing a thoughtful message for the future.

Here are 3 rules you should always, always obey when committing to a version control system.

Always leave a reference to the issue/bug tracking system.

All professional development uses some sort of issue tracking system, to keep track of bugs, new features and other changes to the system. The issue tracking system should always be able to tell who asked for a change, why it was asked for and what considerations was made before the code change. By leaving a reference to the issue tracker, it’s often much easier to get “the big picture” if the change need to be changed years later. To make sure you get it in, just write “Bug #number#: “ as the initial part of the commit message.

Don’t write what, write why

Don’t write it’s a bug fix - most people will know it from look either at the code or in the issue tracking system (see point 1 above), rather write why it fixes the issue (“New check to check for missing parameters”, “Now handles no search result from db correct” - not just “bugfix”).

Keep it brief.

Log messages are not a place to store documentation, user guides or any other important information. You can assume it’s the future you (or another future fellow developer) who will look at the code and try to make sense of it. Think of this, when writing the message - it’s not for the project manager, it’s not for the end-users - it’s for a developer doing maintenance work on the code in the future.