As engineers, we write and commit code every day. Each line of code we introduce is just one small piece of a software system that’s likely to outlast the specific code we’re committing. Our goal isn’t only to ship the code today but to prepare the team to successfully add to and maintain the software system in the future.
Preparing the team for the future means making our code easy to understand by following best practices like descriptive variable names and encapsulating complexity. It also means making our software systems easy to understand by documenting the thought processes that led us to build the way we did.
In Part 1 of this series, we talked about how “why” docs reduce outages, save time, and empower our teams to build better.
In this post, we’ll cover how to incorporate “why” docs as part of your regular building routine using Git and Bytebase.
Choose a Standardized Format for Git Commit Messages
When teams don’t follow a standard format in their Git commit messages, they’re demonstrating they don’t care about their Git history.
The Git history below only has work-in-progress commits. It doesn’t have anything descriptive about the changes we made or why.
Engineers will often forego adding valuable information in their commit messages. This loss will cost time and frustration later when trying to understand past development.
Setting and abiding by a standard is the first step in signaling to your team that Git histories are valuable.
The broken-windows theory
The broken-windows theory in criminology says that
If a window in a building is broken and is left unrepaired, all the rest of the windows will soon be broken.
— via The Atlantic
By leaving a window broken, building owners communicate they don’t care about the building. As a result, the building is likely to fall victim to additional vandalism and crime.
If instead, building owners promptly fix a broken window, they communicate they do care about the building — and so should residents.
Fix broken windows in Git commit messages.
We apply the broken-window theory to our Git commit messages by requiring that messages always follow a standardized format. This sets the expectation that Git histories should be invested in and cared for.
We recommend each message starts with a verb, in the present tense, and ends in a period.
Tip: Update your latest Git commit message with the command git commit — amend.Update any commit message with
git rebase -i HEAD~n
- via Github
Capture “Why” in Your Git Commits
Your code tells other engineers how your code works. But it’s also valuable for engineers to understand why your code works this way. A Git commit message is a great place to document a specific constraint at a certain moment in time because it’s available with the lines of code it directly impacts.
Attaching “why” to your code empowers your team with confidence and empathy.
In Part 1 of this series, we explored how insufficient knowledge can result in blind adoption. The fable of the girl and the fish illustrates the consequences of not capturing “why.” In the fable, a family blindly passes down a recipe from generation to generation without adapting when the initial constraints no longer hold.
By capturing “why” in your commits, including the constraints that impacted your work, you can help future engineers make better choices. “Why” docs give future engineers insights into your building process. With this stronger understanding of the software system, future engineers can have more confidence as they build.
Capturing the “why” in your commits creates empathy within your team.
[Good docs] create an environment where people feel guided and safe when changing the software, especially the newer members of the team. Birgitta Böckeler via ThoughtWorks
By capturing nonobvious thought processes that go into your work, you create an environment that encourages asking questions, not toiling away in isolation. You set an expectation for the amount of context engineers should have when they’re building so they’re empowered to ask for more information when it’s missing.
The “Why” Commit Message
To provide your teammates with the context they need for your code, consider the following questions when writing your commit message:
What constraints were present at the time of coding? What other ways did I consider? If I were reading this in a few months/years, what would I want to know?
- Greggory Rothmeier via RubyConf 2018
Capture the Higher-Level “Why” in Git Pull Requests
Git commit messages are a great place for capturing the “why” that directly relates to a short piece of code. But a feature is usually not just one commit.
Each feature tends to include a set of commits, combined into one or more pull requests from a branch. The feature implementation has its own set of assumptions and its own “why.”
We like to capture this higher-level “why” in the pull-request description.
At Bytebase, our PR description includes:
- What changed
- Any constraints that impacted our work
- Related trade-offs we’re accepting
- Any next steps to do in this thread of work
- What you tested manually
- Screenshots if the UI is impacted
- Any questions for the reviewer
Organizing “Why” Beyond Git
Git commit messages and pull-request descriptions are a great way to add “why” close to the code it describes.
Sometimes we need to understand “why” at an even higher level. For example, I might have the question — Why did we decide to use NoSQL for this project instead of SQL?
In this case, the “why” is best captured at the project level. This is the type of use case we built Bytebase for.
Bytebase is a web app for collaborative notes, where each note is a short byte. For each project-level “why,” you can create a byte in Bytebase. You can then save each byte to relevant buckets, like “Decisions, to make them easy to find later.
You Don’t Need an Overhaul.
We repeatedly hear from engineers they need to embark on an initiative to overhaul their docs. We agree docs are essential to team collaboration, but we’ve found the solution tends to be simpler than teams expect. Just as in our personal lives, the most effective changes are small habit changes, not overhauls — the same is true of our docs.
By adopting a small habit of regularly documenting “why” in Git and in Bytebase, your team can achieve better collaboration that lasts.
Bytebase is the fastest way to jot down and organize notes. Get early access at https://bytebase.io.