The Case for Documenting Code
I regularly read articles from other devs — learning about everything from nitty gritty technical details to big-picture organizational strategies. This week, I read an article advocating against documenting code, prompting me to reflect on its importance in maintaining code quality and fostering effective collaboration.
I love reading Ryan Peterman’s work from The Developing Dev. Peterman writes concisely — within one minute of reading, I’ve learned something new, and I’m done within five. I’d highly recommend his work.
It’s rare that I read one of his articles and find myself in strong disagreement. This week was a bit different, though. I opened my inbox on Friday morning and was greeted by a bold headline: The Case Against Documenting Code.
In your next few minutes, if you’ll let me have them, I’ll explain why documenting code is essential for successful software development.
The case for documenting code
Defining “documenting codeâ€:
- Limited inline commentary, only to explain highly complex or surprising logic.
- Moderate function / class / module level explanations that are concise and informative.
- Significant API documentation, if appropriate (especially if this is a public API).
Why you should document your code
Documenting your code in the aforementioned manner does the following:
- Lowers the barrier to entry for new contributors, thus boosting productivity across a team in the long run.
- Establishes a positive reputation for your tool — be that internal (your team) or external (customers, general public, etc).
- Helps to minimize scar tissue by encouraging more thoughtful design for edge cases — the more complex a design, the harder it is to document, and thus it’s less attractive as a final choice.
Some direct rebuttals
Peterman makes the following claims against documenting code. I’ll follow them with my refutations.
No one actually wants documentation. What they want is the ability to get things done. Sometimes documentation helps us move faster. But that often isn’t the case.
I think folks do want documentation — engaging with it is one of the easiest ways to get over a learning curve. In order to get things done, you need to get over at least some of that sigmoidal beast.
Documentation doesn’t necessarily make your development faster, but it certainly accelerates that of others.
Since software engineering is collaborative, you’d need everyone to remember to update the documentation.
Right. My rebuttal here is simple — enforce updates. Ensuring quality across a team necessitates enforced standards, both in both the technical and process spheres.
That new branch of information is only useful if people read it. Since it’s separate from the code, it’s easy to get lost somewhere.
Aha! Why are your docs separate from the code? That does make things challenging. Integrate the docs easily with tools like mkdocs to ensure documentation is both read and regularly updated.
Positive reputation in the community, tools should be easy to use — people just want to get stuff done.
Some reasonable counterarguments
In all fairness, here are a few ideas that I think serve as logical rebuttals to my general claims above.
Code should be clean enough that internal documentation demands are low.
If a project requires an abundance of internal (worst of all, inline) documentation, it’s the organization of the code that needs reconsidering, not the docs.
And, a few from Peterman:
I’m hopeful that one day, you could chat with the codebase and get up-to-date, simple explanations. Given the improvements we’re seeing in LLMs, I don’t think this is far off.
I do think there’s room to have LLMs assist significantly in writing and interpreting docs. Though, I’d argue we should retain readable documentation, and not just resort solely to LLM interpretations of the codebase.
Engineers need to think about the ROI of everything they do. Documentation is no exception.
I agree fully with this statement. I just happen to be of the opinion that ROI for documentation has the potential to be quite high, if you do it right, and consistently enforce improvements and updates.
Conclusion
It’s simple: docs are remarkably important, and too often neglected.
I write this article as an open source maintainer (for Pydantic, the most popular data validation tool for Python). The open source would crumble without documentation. Needless to say, I’m quite the fan 😉.
If you liked this post, please consider sharing it with others. Thanks for reading along!
