Post originally published on codingwithempathy.com
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. 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.
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
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
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".
Cover-image:Â yuankuei via Visualhunt / CC BY-NC-ND
Top comments (2)
"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."
🙌🙌🙌
I love this, and agree with pretty much everything you wrote. Great post!
Thanks so much Vaidehi! 🙌🙌