Controlling the source of truth - The value of better commit messages
Tags: git, sourcecontrol, communication
Published: 2017-05-08 20:42:17

---
title: Controlling the source of truth - The value of better commit messages
published: true
description: Software isn't finished when it's been delivered. It changes over time and loses its original intent. This leads to async communication, which can go over months or years. I'm talking about the communication that happens through the code we write. And the intent that may be lost
tags: git, source control, communication
cover_image: http://codingwithempathy.com/wp-content/uploads/2016/06/180892741_f0282e7091_o.jpg
---

*Post originally published on [codingwithempathy.com](http://codingwithempathy.com/2016/06/28/controlling-the-source-of-truth/)*

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.

<strong>The end goal of all this communication is software that delivers value to users.</strong>

Software isn't finished when it's been delivered. It changes over time and 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.

<!--more-->
<h2>Breaking down communication in code</h2>
<strong>What -Â </strong>All written code explains <strong>what</strong> it does. Functionally correct code that executes the right end-result through a compiler.

<strong>How -Â </strong>Some explains <strong>how</strong> 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.

<strong>Why -Â </strong>Conveying <strong>why</strong>Â code is how it is. The intent of the software written. Usually using code comments, separate documentation or even good tests / specifications.
<h2>Source control as context</h2>
<a href="https://xkcd.com/1597/"><img class="size-full wp-image-4244 aligncenter" src="http://codingwithempathy.com/wp-content/uploads/2016/06/git.png" alt="git" width="330" height="478" /></a>

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.
<h2>Dotting the i</h2>
The real magic trick of the source control is the commit message. This message has the power to convey context-aware information that <strong>will not change over timeÂ </strong>(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 <strong>whyÂ </strong>a change is being made will make it a lot easier for the next developer (often yourself) to understand the reasoning behind a change.
<h2>The message</h2>
<a href="http://xkcd.com/1296/"><img class="size-full wp-image-4238 aligncenter" src="http://codingwithempathy.com/wp-content/uploads/2016/06/git_commit.png" alt="git_commit" width="439" height="250" /></a>

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.
<ul>
 	<li><a href="http://chris.beams.io/posts/git-commit/">How to write a Git Commit Message</a></li>
 	<li><a href="https://arialdomartini.wordpress.com/2012/09/03/pre-emptive-commit-comments/">Preemptive commit comments</a></li>
</ul>
<h2>A note on issue trackers</h2>
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.
<h2>"Writing good messages is hard"</h2>
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.
<h2>committing to it</h2>
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 <a href="https://blog.codinghorror.com/when-understanding-means-rewriting/"><strong>most of their time understanding code</strong></a>.

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.
<p class="p1">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".</p>

<p><em>Cover-image:Â <a href="https://www.flickr.com/photos/please/180892741/">yuankuei</a> via <a href="https://visualhunt.com/">Visualhunt / <a href="http://creativecommons.org/licenses/by-nc-nd/2.0/">CC BY-NC-ND</a></em></p>