The myth of self-documenting code
If your code documents itself, can you skip writing comments? Not quite – here's the reasoning.
Or, to put it more precisely: it’s an excellent goal that can sometimes be reached, but it doesn’t free you from commenting your code. Every non-obvious spot still deserves a comment – and there are more of them than you’d expect! As code authors, our primary concern is, after all, the comfort of whoever reads the code: above all, we want others, or ourselves in the future, to be able to understand it.
The principles behind self-documenting code are, naturally, sound (and they pay off for other reasons as well): keeping functions/methods small, devoting half of each day to choosing the right names, designing suitable abstraction boundaries, and writing tests that both check the code’s behavior and act as compiled documentation.
Still, there will always be code fragments that leave readers scratching their heads, pondering how best to show the author their “gratitude”. (As it happens, these may well be the fragments that have to be written by hand rather than generated by ChatGPT.)
Such a fragment could be, for instance, an integration with an eccentric third-party service: describe that eccentricity. Or a business rule that, once turned into code, looks like strange bit manipulation, yet genuinely has to be written that way because it sits on the critical path: explain the “why”. Our programming languages are quite expressive, but they do have limits – and once you hit them, don’t hesitate to turn to a comment.
All of this may sound obvious, but how do we spot the other code fragments that need a comment? As a first approximation, rely on common sense (documenting Person getPerson() with gets the person, for example, shouldn’t make it through this filter). Even so, we may turn out to be too optimistic about how readable our shiny new abstraction is.
That’s why, as a second approximation, it pays to look at code review comments, e.g. pull request (PR) / merge request discussions. And ask your code reviewers to point out the places where the code flow was hard to follow.
When a PR contains a discussion about a specific code fragment, it should always result in refactoring the code, adding a comment to it, or both. The very fact that a PR attracts any comments or questions at all shows that the codebase isn’t actually self-documenting.
Discussions in PRs and issues are handy and help shorten the feedback loop. Make use of the information they hold, and don’t let it die! Don’t be afraid of duplicating it: whoever is lucky enough to modify the code in the future will read only the code – they won’t dig through the whole PR merge history and the discussions attached to it. Unless, that is, they become truly angry and desperate – but let’s try to prevent that.
At the very least, give them some context in the form of an issue number or a backlink. Better still, put the relevant information right in the code. Issues and PRs are forgotten as soon as they’re merged.
“But wait!”, you might object, “documentation goes stale!”. True, and comments drift out of sync with the code they describe. That’s certainly a problem. It’s especially true, though, when the documentation lives far from what it documents. Comments are better positioned: you can place them inline, right next to the logic, which lowers the risk of them becoming outdated.
One more argument in favor of code comments: when it comes to the source code itself, the source code should be the central source of truth. We’ve already noted that information scattered across several places – PR comments, issue descriptions, and the source code – is hard to navigate. On top of that, it’s partly subject to vendor lock-in. Git is a distributed version control system, so everyone holds a complete, regularly updated backup – but only, of course, of the information that actually lives in git.
PRs, issues and our heads hold plenty of information: don’t leave it there! And don’t let it die! To sum up:
- even the cleanest code bases need comments
- treat code review comments as signals of where a refactoring or a comment is needed
- capture the “why” using the context from the issue/bug report you’re working on
- move anything important from an issue or a PR/MR discussion into the code base – via naming, code structure, or comments
- make the source code the central source of truth about the source code.