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.
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.
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.
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.
Other times, the code changes often. Some poster-children for fast code change are startups, corporate-funded open source projects, prototypes, and marketing sites.
Likewise, sometimes the people change often. Consultancies, startups after raising their second round, lightweight but heavily-used open source libraries, fintech.
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.
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.
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.
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.
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.
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.
