--- title: We are storytellers along the code-people change continuum teaser: A commit message is a tiny story. tags: playbook,comments,commits,stories author: Mike Burns published_on: 2020-11-23 --- Software is written for other people. This is true in the sense of "for other people to use", but also in the sense of "for other people to read." This is why we use programming languages of higher abstraction and readability instead of [some sort of portable assembly][]. [some sort of portable assembly]: https://llvm.org/ "LLVM" Readable software tells a [story][]. There are many ways to write a feature, but only one was chosen. The others might be considered, but ultimately ruled inappropriate. There might be adventures along the way -- bugs encountered, prior decisions worked around or refactored, new library or framework features discovered -- that fit into the story. [story]: https://quoteinvestigator.com/2015/05/06/two-plots/ "There Are Only Two Plots: (1) A Person Goes on a Journey (2) A Stranger Comes to Town" How we share these stories exist along what I'll call **the code-people change continuum**. ## The Code-People Change Continuum Code changes, and the people understanding the code change. This is what life is all about. Sometimes the code is pretty static. This can be seen in academia, where the goal is to spend four years getting one file to compile, [publish, and never touch it again][]. A lighter version is in blog posts and documentation, but with a goal of five minutes instead of four years. [publish, and never touch it again]: https://hackage.haskell.org/ "Hackage" Sometimes the people are static. Government and bank projects in [COBOL][], health and government projects with high entry requirements, [obscure open source projects][]. Tiny companies with [a good utility product][] and [a clear business plan][]. [COBOL]: https://logicmag.io/care/built-to-last/ "Built to Last" [obscure open source projects]: https://www.openbsd.org/innovations.html "OpenBSD Innovations" [a good utility product]: https://basecamp.com/ "Basecamp" [a clear business plan]: https://craigslist.org/ "Craigslist" Other times, the code changes often. Some poster-children for fast code change are startups, [corporate-funded open source projects][], [prototypes][], and marketing sites. [corporate-funded open source projects]: https://www.kernel.org/ "Linux" [prototypes]: https://www.youtube.com/watch?v=Gzj723LkRJY "Whoops!" Likewise, sometimes the people change often. [Consultancies][], startups after raising their second round, lightweight but heavily-used open source libraries, [fintech][]. [Consultancies]: https://thoughtbot.com/blog/team-rotations "Team Rotations" [fintech]: https://cointelegraph.com/news/coinbase-hemorrhages-employees-following-controversial-culture-stance "Coinbase hemorrhages employees following controversial culture stance" Where the code-change and people-change lines intersect each require their own mode of storytelling. ## A case for code comments When we say that the code doesn't change often, what we imply is that the story is done or slow-moving. We can easily make the story fully accessible in a central place: we can tell the story alongside the code. This is valuable regardless of how many people see it, but the more people see it, the more clear our formatting should be. Take a low code-change/low people-change project, such as a niche open source tool. The story -- that is, the code changes, why they were made, what problems were encountered -- is complete. It is also well understood by all who are interested. This is where inline code comments rule the world. A [short paragraph][] before an oddly-named variable, or perhaps [some choice curse words][] before a complicated architecture-dependent algorithm, all convey the story appropriately. [some choice curse words]: https://cdn.kernel.org/pub/linux/kernel/people/marcelo/linux-2.4/arch/sparc/kernel/ptrace.c "an essay relating SPARC, chainsaws, and the human body" [short paragraph]: https://www.bell-labs.com/usr/dmr/www/odd.html "Odd Comments and Strange Doings in Unix" Conversely, a low code-change/high people-change project, such as documentation or a published paper, requires a different level of refinement. Those are examples where the whole point is for large masses of people to read and understand the code. This is what [Literate Programming][] was designed for -- telling the complete story about the code as it currently is and why it is that way. The details about other considerations will often be included here in a well-reasoned guide of why the documented code was the selected methodology. [Literate Programming]: https://www-cs-faculty.stanford.edu/~knuth/lp.html ## The story as a separate entity Now we consider fast-paced code. This codebase [grows in an uneven blob][], and new bugs are often mis-understandings or even ignorance about other parts of the code. It cannot reasonably be documented as a whole, but can be better understood by the changes it went through. [grows in an uneven blob]: https://www.youtube.com/watch?v=MkJxlKD2bjk "gource of Linux" In a high code-change/low people-change project -- rapid development by a small team with no expectations to grow -- these changes can be represented in the ticket tracker. The features and bugs, and their discussion thereof, tell the story. A strong [async][] development workflow with a lightweight project management tool means that people can trace bugs back to the ticket where it was introduced, to help the bug fixer understand what led to the misunderstanding and what the original goals were. [async]: https://thoughtbot.com/blog/pay-the-cost-upfront-dont-distribute-it-to-others "Pay the cost up front. Don't distribute it to others." And finally we have the high code-change/high people change project. There is a tool for best documenting the story here: version control. A [history][] of [well-written commit messages][] means the people investigating bugs, understanding blockers, or simply trying to grasp the complexities of a project can read through the commit messages to understand what happened. **A commit message is a tiny story** [explaining][] the struggles, the daring adventures, and the journey -- all with a known tidy ending (the commit exists!). A commit message has the bonus that it can also link to discussions on the ticket tracker and the merge request. [history]: https://thoughtbot.com/blog/write-good-commit-messages-by-blaming-others "Write good commit messages by blaming others" [well-written commit messages]: https://thoughtbot.com/blog/5-useful-tips-for-a-better-commit-message "5 Useful Tips For A Better Commit Message" [explaining]: https://jeremykun.com/2020/01/14/the-communicative-value-of-using-git-well/ "The Communicative Value of Using Git Well" ## Be a storyteller Be a storyteller as you move through your projects in life. Find the audience and how they can best receive the message -- comments, Literate Programming, ticket trackers, commit messages, or perhaps something else -- and share your heroic adventure with others.