Comment Only What the Code Cannot Say | by Kevlin Henney | Medium
Posted by jpluimers on 2025/08/13
Often after having taught a topic for decades, somebody rephrases it in a beautiful concise way:
[Wayback Comment Only What the Code Cannot Say | by Kevlin Henney | Medium
Kevlin has the same two quotes I have included teaching software quality for a long time:
In The Elements of Programming Style, Kernighan and Plauger note thatA comment is of zero (or negative) value if it is wrong.Instead of writing apologies and apologia, follow Kernighan and Plauger’s advice from the 1970s:Don’t comment bad code — rewrite it.
And his post-title is absolutely spot on as is his conclusion:
Any shortfall between what you can express in code and what you would like to express in total becomes a plausible candidate for a useful comment. Comment what the code cannot say, not simply what it does not say.
He makes many great points about code and comments, some of which can condensed to “remove code and comments that do not add quality”.
This holds even more so for mediocre comments as they tend to survive because they are plain text to the compiler and refactoring tools. Mediocre has a much higher chance to be improved because of our IDEs ad tools are so good keeping track of where code is referenced from.
You might say that they then will be lost forever. Well, that’s what version control and good commit-messages are for. That’s part of your documentation treasure.
Be sure to read the rest as well, as he not only describes what quality comments are about, but also elaborates for instance on how (and why!) noisy code and comments hinder software developers and how to follow-up on code that needs explanation, like:
- better naming identifiers
- splitting long methods into shorter ones having meaningful names
Recommended reading!
Oh, hey, I just noticed: Kevlin wrote it on my 51st birthday right when I was preparing to undergo my first big rectum cancer related surgery. What a coincidence!
Via
- [Wayback/Archive] Bart Enkelaar on Twitter: “As usual, @KevlinHenney nails the “to comment or not to comment” not-so-dilemma.”
- [Wayback/Archive] Kevlin Henney on Twitter: “Comment Only What the Code Cannot Say This expanded version of one of my @97_Things Every Programmer Should Know pieces seems to have gathered some recent interest, so reposted here for anyone who may also find it interesting.”
–jeroen
The Wiert Corner - irregular stream of stuff 
Leave a comment