The Matrix: Writing Code That Doesn't Need Comments

In the early days of programming, opening an old, convoluted codebase feels like entering a dark dungeon with no torch. One such file, named processData, stretched to 800 lines, filled with cryptic variable names like tmp, x, and flag. Comments attempted to explain each line, but the codebase was a mess. The author spent three hours trying to figure out why an edge case produced an empty array, only to discover an outdated comment that no longer matched the actual threshold.

This experience inspired the question: could code be written so clearly that comments became unnecessary? The answer was discovered in a mindset shift towards self-documenting code, achieved through intention-revealing names and small, focused functions. A well-written sentence like "She opened the door and stepped into the rain" conveys meaning without footnotes—similarly, clear variable and function names communicate intent without explanatory comments.

Self-explanatory code stays accurate as long as names remain accurate, eliminating the need for outdated comments that become noisy maintenance liabilities. The author shares a before and after example of code with comments versus self-explanatory code. The original code had comments explaining tax and discount logic, which would need updating if those rules changed.

The refactored code uses function names like calculate_cart_total, _apply_discount, and _apply_tax_if_needed, with variables like subtotal and amount clearly conveying their roles. Logic is split into tiny, pure functions, each doing one thing, making the flow obvious without comments. If tax rules change, only _apply_tax_if_needed needs updating; if discount calculations become more complex, _apply_discount is edited.

The main function now clearly summarizes the process: get the subtotal, then maybe add tax. Common pitfalls to avoid include over-abbreviating names, leaving stale comments that contradict code, and creating god-functions (very long functions hard to follow). Adopting this habit improves code reviews by focusing on logic rather than deciphering variable meanings, making onboarding new teammates easier, and reducing the mental tax of "comment drift."

Writing self-explanatory code lets developers focus more on building features instead of fixing documentation mismatches. To apply this, the author challenges readers to refactor a small, uncommented piece of their own code, noticing how the need for comments fades away. They suggest sharing the before/after with a teammate and asking if they needed any comments to understand the refactored code.