by Serguey Shinder
Early in a job I inherited a file with a comment near the top that explained, in a friendly tone, why a certain value had to be exactly thirty seconds. It read like advice from a wiser predecessor, and I treated it that way. For months I routed around that number as if it were load-bearing, careful never to disturb the thirty seconds the comment had warned me about.
The problem came when a real issue traced back to that exact timeout. Thirty seconds was too long for the case in front of me, and the comment insisted it could not be shorter. So I went digging into the history to understand the constraint the comment described. There was no constraint. The number had been thirty since the first commit, and the comment had been written by someone guessing at why, long after the fact, to make the file feel explained.
The comment was not malicious. It was worse than that. It was confident. Someone had felt the discomfort of an unexplained number and resolved it by inventing a reason, and that invented reason had then protected the number from every person who came after, including me, for years.
That taught me to distrust the most reassuring thing in a codebase, which is prose that explains itself. Code cannot lie about what it does, only about what it means. But a comment can be sincerely wrong forever, because nothing ever runs it, nothing ever tests it, and nothing ever forces it to stay true as the code around it drifts.
I changed the timeout, deleted the comment, and wrote nothing in its place. The absence felt honest. If the next person wonders why the number is what it is, they will do what I finally did, which is read the code and the history rather than trust a story someone told about them.
I have not stopped writing comments entirely. But I write far fewer, and only about things the code genuinely cannot say for itself, the why behind a decision that looks wrong but is not. I never again write a comment that guesses at intent I do not actually know, because I have felt what it is like to be on the receiving end of that guess, treating a stranger’s invention as law.
The craft, I have come to think, is not in explaining the code. It is in writing code that needs less explaining, and being ruthlessly honest in the small places where words are truly required. A wrong comment is worse than no comment, because it does not merely fail to help. It actively lies with a friendly face, and it keeps lying long after everyone who could correct it has gone.
– Serguey Asael Shinder
Leave a Reply