Commit Discipline and Comments: Be Kind to the Future

Suppose you are happily coding away, about to finish a new feature on a shiny new product. You attempt to run your code when an ugly exception rears up from the middle of some code that you call, but did not write yourself. You attempt to use your team's version control software to figure out who wrote that code, and what sort of changes have happened to it that might be the source of the problem. Alas, your version control software reveals that Joe, who left the project months ago, wrote the code throwing the exception. What's worse, there is no clue as to why the last changes to this component happened. The most verbose comment in the system is a forlorn line saying "fixed bug."

Version control systems almost always allow the person making a change to make a comment when committing. Some people never make any comments, asserting that the code should stand on its own, and other people write whole paragraphs describing what they changed. If I have a choice, I'd prefer to find a line or two of comments for each commit, describing why the code changes were made. The code itself describes what was changed, but especially in a project where the team will have some churn, I'd much prefer to find out the intent behind a code change from a commit comment, than be left scratching my head about it.

In the Agile software development community, a healthy dialog has been happening about the proper role of comments in source code. Comments in source code are often redundant and at worst, unrelated to the actual functioning of the code. Making relevant comments can help your teammates, present and future, but placing comments about a global refactoring in the source code would be pretty redundant. By placing comments about why you are making a change in the commit log, you can move your communications about why a change has happened to a higher-level space.

When I commit my changes, I typically write a line or two of text that describes the change. If I'm working on a project that uses a formal issue tracking system, I try to reference the issue number in the commit. Some In an Agile environment, where testers write down in-iteration bugs on white boards, the description of a bug may be gone forever once it's fixed. If someone has written a bug on a white board, I'll often use at least part of the bug description on the white board in the commit. Here's an example adapted from the project I'm working on:

Fixed bug: lines of text are disappearing in comment control on save
Refactored GridView column handling to use hide/show instead of removing columns

Notice that the comment has a hint of why in it, it does not stop at what changed.

A commit comment for a change set that adds features might look like:

First cut of new story: recover password by using email address on file


Making brief comments at version control commit will help whoever touches the code next understand what is happening in the software and why. Sometimes, after a few months away from a code base, I even forget why I made certain changes to a program, and them I'm extra glad that I have this habit of making comments at commit.