Use git to comment your code (and stop writing rubbish commit messages, please)
Over recent years we've seen the software community debate the usefulness of comments (this article being an example), and rightly so. The main argument is against explanatory comments, i.e. "this code is doing X", as the ideal situation is that the code is written in a way that means it's readable and self-explanatory. The problem with comments like this is that they easily become out of date, as someone makes a quick change to the code without reading and updating the associated comment. You then have the issue of a comment which directly contradicts the code it's meant to be explaining.
Another kind of comment that doesn't belong in the code is one like "I changed this because...", or what I'll call revision comments. I'd argue that these comments are just as prone to becoming out of date and contradictory as explanatory comments, and that they actually belong in the logs of your version control system. Git tracks the way your code changes over time and stores a human readable description of what changed at each commit. If your commit messages are written with this in mind then they become more like documentation for the history of your code.
The scourge of lazy commit messages
Have you ever thought about the purpose of your commit message? Do you write it thinking that nobody will ever read it again? Do any of these sound familiar?
- added feature x
I've absolutely been guilty of this in the past. If you consistently write commit messages like the above then you can guarantee that no-one will ever read them, as they're practically useless. They'll eventually be able to work out what changed by looking through the diffs of your commits, but they won't necessarily be able to work out why you made those changes. This valuable piece of information exists only in your head, and probably only for a few months at most.
On a more basic level, if you want to reset your codebase to a particular commit, scanning through a series of commits that don't have descriptive names means that you have no choice but to check the diffs. Don't do that to someone - it's mean.
Have you ever been in the situation where someone asks you why you made a particular change, only for you to come up with a total blank? Or, if you reverse the situation, have you ever looked at someone else's code and needed to know why it's evolved the way it has? I know there have been times where I've made some code "simpler", only to find that there was a very specific reason as to why it was written that way, and I've broken it.
The ideal situation is that our commit messages are targeted, clear and relevant, first describing the change and then why it has been made. You can then call on the git logs to describe the changes to a repository, a single file or even a given line in a file. Using these logs can help future developers (and future you) to know if they're about to make a big mistake in changing something that you changed for a very good reason 17 months ago.
Make regular, smaller commits
Although I've come a long way in writing descriptive commit messages, I still sometimes forget to commit regularly when I'm in the flow of things. This means that I end up committing a huge chunk of code at a time, with multiple unrelated changes. When this happens, it's pretty much impossible to write a useful commit message.
If you can't describe the changes in a couple of setences, it's best to break it down in to multiple commits. And if you make multiple changes that are totally independent of each other then they should go in separate commits. This is useful not just for providing clear commit messages, but also if you need to revert the changes introduced by a single commit. I've been in the situation where I've had to undo one half of a large commit that someone made a while back, and I can promise you that it's not fun.
A case study for "commenting" your code with git
Let's say I have a web app that involves a very common task: validating user-submitted passwords. Here's the very simple class that does the job:
Here's the commit message:
Even if you aren't familiar with ruby, the commit message explains what the class does at this stage. There's no need to add a comment to the code, as it's very simple. But even if you did want some detail, the git log will always be there, unlike a comment which can easily be deleted.
NB: I like to write git commit messages in the present tense, imperative style, as recommended by git itself. This is because each commit is a description of how it changes the codebase. So I use "change" instead of "changes" or "changed", and "fix" instead of "fixes" or "fixed".
All code is susceptible to change. And in this case, after some testing, we've realised that we've got a potential bug in the code: there's no maximum limit on the length of the password, but our database column only allows 64 character strings. To avoid truncation, we update the regular expression:
The commit says not only what changed but, crucially, why it was changed. The code is kept clean, without being littered with comments, but the history of the code is always available on demand.
If we carry on in this vein, this class will have a history of detailed and specific commit messages, as opposed to a series of "Updated password validator" messages.
How to see the code history
There are a number of commands that will help you view commits over time and, combined with the long list of possible arguments, practically endless ways of viewing the information. Here are two that I find particularly useful.
Run without any arguments,
git log will show you all commits in your current branch, in descending date order. You can make this more targeted by showing only the commits that affect a single file, with
git log -- <path/to/file>, and you can even show the full diffs alongside with the
You can also view the commit log for a specific line (or range) with
-L, and using the format
The name of this command suggests a certain level of aggression, but I find it helpful to get an overview of how a file has been affected by commits over time. The output gives each line of a file prepended with the details of the most recent commit that affected that line, including the author of that commit:
You can view the full commit with
git show <commit-sha>, to see the commit message and full diff.
Better commit messages can save you and people working on the same project from potential future headaches, and will help you to learn why your code has evolved in the way it has. This will add a certain level of protection against bugs, and works as a kind of documentation. Get to know
git log and
git blame, and use them to understand the code your about to change.