Comments, Tests, and Commit Messages are All Documentation
Once upon a time, I said outloud “If I ever get a tattoo it will say «The Docs Lie».” This was a response to a colleague asking that we should collectively write more documentation.
Two years later I wrote Code is a Conversation.
At the time, we were working in a highly volatile code-base. I found it draining to even think about taking time to write documentation. Writing documentation, like writing tests, means considering what is the context of what you’re writing. And when I knew that things were changing rapidly, I couldn’t justify the extra time expenditure of writing more documentation.
At my first job, we maintained a data dictionary. That data dictionary spoke to the purpose of a table and it’s fields. Over time, that data dictionaries accuracy drifted. But I still found it useful to understand the initial intent of a database table and it’s fields.
As I’ve worked and maintained systems, I’ve learned that understanding the intention of the code is perhaps the most important thing. Which is why, when I start writing a new object or method, I try to begin with the code comment: “The purpose of this…” After all, when it comes time to refactor or remove code, understanding it’s history is often critical.
I also spend time with my commit messages; to speak to the prior state, the new state, and the why of the change. With good commit history, you can use annotation tools to get a sense of how a method has changed.
I understand that some conversations happen in the pull request review, but I find it useful to take the salient points and fold them back into the commit messages.
I look at writing documentation, commit messages, and tests as a love letter to future self. Present me is telling future me, “I value your time and energy and hope you can use what I am giving you.”
In years prior, I didn’t do that, and what I found was that I struggled with maintaining those code-bases. By taking time to write not just the code, but commentary on the code, I developed a richer understanding of that code-base and the problems it was attempting to solve. And from that understanding, I could better remember details and reason through even more complicated abstractions.
For those looking at my Forem pull requests, I hope these considerations are evident. Yes, my hope would be that the code could speak for itself. But when paired with code comments, tests, and commit messages, I’m aiming to foster conditions that best prepare code reviewers for the task ahead: engaging with someone’s creative efforts, attempting to understand what’s happening, and ultimately passing.
It’s one of the most important tasks any developer can do. To answer “Should this version of change be something that we collectively accept and are prepared for supporting?”
The Guide May Not Be the Best Map Maker
In , I wrote:
As a general rule, I don’t read code comments. My brain filters them out.
More specific, I don’t read code comments that say what the code is doing. The code is the authority on what it is doing. Anything else is subject to being incorrect.
But when I find a comment that explains why the code was written, I am always thankful.
Tell me why you chose:
- an obtuse port
- a confusing looping structure
- a particular dependency
- a dense method —Code is a Conversation
This still stands, with a caveat. When I start a new method, I’ll say what the method is doing. I won’t go into the implementation details, but use it as a chance to frame “what am I trying to accomplish.”
I still struggle with writing the higher level documentation. After all, who’s the intended audience? Am I the right person to convey that information?
My grand father lived his life in a rural county of Indiana. When he gave directions, he would provide references that were very detailed. I can almost hear him saying “Turn left at Eli Bontrager’s farm then go until you get to the shade tree we used during harvest; You know the one just past the Old Swartzendruber sugar bush.”
In other words, how does my familiarity with the implementation details of a code-base hinder my ability to write about that code-base for different audiences.
Conclusion
I’m sharing this to give insight into my journey as a developer that once firmly believed that documentation lied. But I’ve refined my stance. I use the documentation, specs, commit messages, and implementation details to help triangulate on the underlying truth of both intention and implementation.
I find that spending effort explaining things in the different “languages” of software development helps me better understand and remember both the change and it’s interaction with the larger ecosystem.
Further Details
I’ve long used the YARD documentation format. I frequently reference the Tags Overview. I find that format quite legible and verbose for what I want to convey with inline documentation.
I also look to Tim Pope’s A Note About Git Commit Messages as guidance for writing commit messages. Please keep the first line of your commit message short. It helps with the various tools.
And for tests, I’ve favored RSpec , which has ample support for crafting expressive tests.
Top comments (2)
Bugfix: It looks like there's a paste error in the first paragraph: "we write collecively should write" should probably be "we should collectively write".
Patched!