Communication, Craftsmanship

Controlling the source of truth -The value of better commit messages

Working as a developer involves communication on many levels. We need to communicate with business stakeholders in a domain specific language, abstracting away much of the technical jargon. Team communication on the other hand is a lot more technical, and closer to our reality in code.

A lot of our communication is silent though. It happens through async tools like email, Skype or Slack. I’m sure that anyone that’s attempted communicating this way has experienced how easy it is to under-communicate, leading to a ping-pong of messages before the intent and understanding is conveyed.

The end goal of all this communication is software that delivers value to users.

Software isn’t finished when it’s been delivered though. It changes over time and with it loses its original intent. This leads to even more async communication, which can go over months or years. I’m talking about the communication that happens through the code we write.

Breaking down communication in code

What – All written code explains what it does. Functionally correct code that executes the right end-result through a compiler.

How – Some explains how it’s done. Code has to be readable and understandable. Clean code and focus around patterns and practices like BDD / DDD are all approaches of bringing the ubiquitous language of the problem domain into the code base. Making it easier to understand how logical business components work. The rules involved and how they interact with other bounded contexts.

Why – Conveying why code is how it is. The intent of the software written. Usually using code comments, separate documentation or even good tests / specifications.

Source control as context

git

A challenge with code over time, is that it evolves and changes based on requirements and needs. If a team has great discipline then tests / specifications / documentation will evolve with it, but there’s always a tendency for that to rot, become stale or even be blatantly wrong.

This is where we can turn to our source control to help. Any given commit in a repository is a snapshot code base, displaying changes to our code and the overall state of that repository. More importantly though, it shows the context in which code was changed.

The context gives us information like when a change was made, who made it, which other files were involved, and where it fits in the history of the repository. This all aids us when trying to understand the context of how the code has evolved to where it is.

Dotting the i

The real magic trick of the source control is the commit message. This message has the power to convey context-aware information that will not change over time (yes, you can rewrite source-history sometimes, try not to overdo it). But it can convey the intent of a change in a way that gives meaning to a developer.

Writing a message that explains why a change is being made will make it a lot easier for the next developer (often yourself) to understand the reasoning behind a change.

The message

git_commit

Herein lies a challenge for many developers. Either they don’t really care about the value of good commits and commit messages, or they focus too much on the technicality around micro-commits with technical changes or the message format.

Writing good commit messages is a skill alongside coding that needs to be practiced. Focusing on logical commits that convey thought and intent is where the value lies.

How the messages are formed is a matter of opinion, taste and preferences for the given code base and team, but here are a few resources to get you started.

A note on issue trackers

Issue trackers are awesome when connected to our source control. By explicitly connecting our commits to issues we can have proper discussions and capture a lot more of that said intent. But if you ever change issue-trackers without the possibility of moving history, all that valuable communication is “lost” in the context of reading code.

“Writing good messages is hard”

Writing good messages is hard the same way that writing good code is hard. You need to understand the “why”. Look beyond the user story telling you what to do, and focus on why the change is required to begin with.

committing to it

Why this focus on understandable code through context and communication and writing skills? Unless you’re not already convinced that communication and context are valuable to you and your team on a daily basis, there’s the fact that developers spend most of their time understanding code.

Look past the technical details of message lengths and how to format a commit message, but rather focus on the value of conveying intent of why changes are being made in a concise and understandable way.

At the end of the day, when all the original developers have moved on and the documentation is out-dated, our source control is where we can look to find the “truth”.

Thanks to Marius Gundersen & Tomas Ekeli for the resources and inspiration for this post.

Please feel free to reach out to me directly if you have any thoughts, questions or criticisms. Or leave a comment below.

Cover-image: yuankuei via Visualhunt / CC BY-NC-ND

 

 

 

  • Kevin O’Shaughnessy

    Another very nice post. Are there any approaches you can recommend for improving the quality of the team commit messages?

    It is easy to make commit messages mandatory, or a minimum of a certain number of characters, but there is, in my view, only a very loose relationship between length of commit message and quality of commit message. A good commit message is like good code: it has a high signal to noise ratio.

    I hate it when someone checks in a 100 file changes in one go and only writes one short sentence in the message. The best automated rule I can think of would analyse the number of lines of code changed and dynamically set the minimum length of the commit message based on that (non linearly). I have never seen that actually done, but even if it were, beyond that it’s all human judgement.

    Code reviews are commonplace, but commit message reviews are not. With code reviews, there is always a chance that the reviewer will disagree with the author, and if that happens the two developers need to discuss that. Should commit messages be reviewed as well? Have you seen any detailed guidelines for commit messages, or is a good idea to have them?

    • Hi Kevin, thanks so much for dropping by and leaving some great questions. Here’s a few answers and some opinions.

      I agree with you completely in regards to the signal to noise ratio in commit messages. Keep it concise and to the point.

      I’ve never been one for long commit messages, nor have I really cared about the structure. There is a well-known git-convention of 50 chars for a topic and 72 for the body. Optimally the input UI / Console editor should sort this out for you, otherwise just type away.

      I try to group commits based on logical / functional changes, even large ones when they make sense. Basically taking your task / story and slicing it down to a set of logical pieces of work – which is what you should be doing anyway.
      This also fits quite well with TDD, where Each Red / Green / Refactor cycle is a commit. If the new test is related to the previous, then I just amend. Again it’s about getting to those atomic / logical commits.
      Here’s an article on that: http://www.freshconsulting.com/atomic-commits/

      A rule-of-thumb is the “revertabilty” of a commit. Aiming for the ability to go back and just revert a commit if needed. If you need to partially revert commits, then you’re not making logical changes. But this is a grey area. I’ve rarely needed to revert commits.

      I also like to commit code and tests/specs together and keep the code compiling between each commit. You should be able to checkout out any commit and build / run tests.

      I try as much as possible to write the commit message before I write any code. So-called preemptive commit messages. I’ve found that to help my focus a lot, and makes easier for the reviewer.

      We practice code-reviews and commit messages are a part of that, but they don’t undergo any changes. So a well-written / committed story is easier to review compared to a poorly written one. There are a lot of different styles of commit messages though, some conveying great info, others which are long with little info. Some messages are a reflection of the code implementation. There is no value in messages like that. – We’re currently exploring a guide to commit messages for our team / repos so we can align a little more.
      This is a great starting point, at least: http://chris.beams.io/posts/git-commit/

      But as always, it depends. I would actually like to try a strict Topic(50) / Body(72) approach and see how that actually would work.

      Looks like there’s enough here to do a follow-up post 🙂

      Thanks again Kevin.

  • Pingback: Valuable Resource 🎞: "Communication is just as important as code" - Coding with Empathy()

  • Pingback: Capturing Intent - Making sense of code - Coding with Empathy()