Towards self-documenting code — part I
This is not a case against code comments; it’s about favoring a self-explanatory and self-evident codebase. Comments become superfluous as a side-effect.
In most cases, if you rely on comments to explain code, you’re doing it wrong. I’ll show you some ways to achieve self-documenting code. No, it’s not utopic.
No comments by default
In my case, the “code-needs-comments” myth comes from the university. However, the rule to make your code self-explanatory rather than using comments existed in all the companies I was at, and it worked out fine. So, what are the problems with code comments?
Subjectivity. Comments are subject to the reader’s interpretation. Natural languages are ambiguous, but code doesn’t lie.
Code never lies; comments sometimes do. (Ron Jeffries)
They allow lousy code to exist. Comments are an excuse to make bad code with good explanations.
A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail. (Robert Martin)
They quickly get outdated. The code is the ultimate source of truth, so why have another? Code changes while…
