What Commit Messages Say about Developers and Test Automators
Commit messages say a lot about the developer or automated tester who writes them—or who doesn’t write them at all. Trivial on the surface, the presence and substance of a commit message can indicate how forward-thinking a person is, which may indicate bigger things about the code or the project itself.
One could infer that a person who writes a good commit message is thinking about the team at large and the future of the coding effort, which could mean that person is also striving to write clean, maintainable code. Writing well-formed commit messages is one of those little habits that helps build quality in from the ground up.
Commit messages are useful for a number of reasons. If you need to track down when a change was introduced, reading the commit log is easier than diffing the files to determine the changes there. If you forgot why you changed something, reading a commit message for the detailed reasoning brings you up to speed quickly, freeing your mind from having to store and recall such information.
In addition, writing the commit message helps your brain withdraw from code mode and see the bigger picture of what exactly you did or didn’t do, perhaps triggering a reminder of something you forgot to do. Commit messages are useful for the obvious reason that few of us work in isolation; other people need to understand how the code is evolving.
So what’s the recipe for a good commit message? A good commit message includes the issue number or issue url at the start, or at least the section of the application changed, if there is no issue number or url. A well-formed message describes the changes made to logic and behavior. It says, “Things used to work this way, but now they work a different way, and here’s why.”
A good commit message may also indicate side effects of the change. Too many side effects may reveal a situation where a single commit is doing too many things and should have been committed in smaller chunks.
Keep in mind that good commit messages document change; after all, a commit is a change. They do not function like or replace code comments, which document the current state of the code and are another very useful item for building quality in. If you’re stating what the code does and why, that information would probably be useful for people looking at the code in the future, so that would make a good comment in the code itself.
Likewise, documenting how the code used to work wouldn’t make sense as a comment for someone reading the code down the road, but it does make sense for a commit message.
Taking a few extra minutes to thoughtfully document your changes is a practice that can make your life easier and add considerable value to your team.
