One delightful unintended consequence of the shift towards collaborative coding with Git is Commit Logs From Last Night. As the domain name suggests, this website shows a running list of humorous commit messages on actual GitHub repos. You can watch an endless stream of developers writing funny commit messages and laugh as you empathize with their pain.
It’s not the salty language that makes it funny, but rather the sense of palpable frustration you can see as developers code. Though we often expect our code to flow forth straight from our brains to the terminal, the reality is usually more muddied. You code by trial and error and we’ve all been there in caffeine-addled disgust at 2am wondering why this simple change won’t work as expected. We’re basically stumbling our way through print statements and console logs to glory.
Of course, Salesforce commit messages are important. But most people are not trained on how to write them. We learn by following what others are doing. And unfortunately a lot of us are just hacking our way to a solution and writing short, shallow commit messages like the ones above.
Writing Good Commit Messages
+ header line: explaining the commit in one line + + Body of commit message is a few lines of text, explaining things + in more detail, possibly giving some background about the issue + being fixed, etc etc. + + The body of the commit message can be several + paragraphs, and please do proper word-wrap and keep + columns shorter than about + 74 characters or so. That way "git log" will show things + nicely even when it's indented. + + Reported-by: whoever-reported-it + Signed-off-by: Your Name <firstname.lastname@example.org>
There are 3 key elements to a good commit message.
The header is where most people start (and stop) with a commit message. The header is a one line high-level summary of what the commit includes. It’s like the subject line of an email.
Though there is no hard rule, many blogs like tbaggery suggest 50 characters as a good headline length. You should always follow the headline with a blank line so that it can be identified as the subject. Tim Pope enumerates some of the commands you can use when you format correctly:
- git log –pretty=oneline
- git rebase –interactive provides the summary for each commit in the editor it invokes if the config option merge.summary is set, the summaries from all merged commits will make their way into the merge commit message
- git shortlog uses summary lines in the changelog-like output it produces
- git format-patch, git send-email, and related tools use it as the subject for emails
- reflogs, a local history accessible with git reflog intended to help you recover from stupid mistakes, get a copy of the summary
- gitk has a column for the summary
- GitHub uses the summary in various places in their user interface
According to Tim Pope:
The subject/body distinction may seem unimportant but it’s one of many subtle factors that makes Git history so much more pleasant to work with than Subversion.
Commit Message Body
Most people never get past the headline. When I was learning to code and use Git, I never included more than a one line summary. Because I so rarely saw long, detailed commit messages I assumed there was some sort of hard limit on the number of characters you can have in a commit message. But this is not so! Linus himself suggest that we offer longer descriptions with our commits so that people can follow in more detail with what the commit includes.
For many software projects, commit messages are the only documentation. So it makes sense to take the time to write more detailed commit messages. When your colleagues want to know why something was implemented the way it was, they can look to the Git history to understand better how an Apex Class or VisualForce Page evolved over time. They can see when and why you added a particular method and what it’s function was.
It doesn’t just help your colleagues. A good commit message that you wrote can sometimes be a lifesaver. It’s as if a future version of yourself came back and said to you, “Hey, you’re going to need to know why this method was added someday and here is the reason.”
Finally, Linus recommends a “reported by” and “signed off by” signoff at the end of the message. This is less important than the header and commit message body, but can still be useful when sorting through thousands of commit messages.
Linus suggests keeping word wrap to 74 characters or so. Most terminals are 80 columns and using 74 characters or so keeps you commit message nicely indented when you type
git log. Whatever text editor you use should allow you to set how many characters you want in your commit messages.
More and more Salesforce teams are moving to Git for their source control.
Writing good commit messages doesn’t just help your colleagues and future self. Taking the time to write them gives your brain the time and space to think about the why and how of your code. This makes it easier to ensure that your commits are of high quality and that there is a good reason behind every change. Pausing every so often to get this kind of information is invaluable.