The Matrix: Writing Code That Doesn't Need Comments

The Quest Begins (The "Why") I still remember the first time I opened a legacy codebase and felt like I’d stepped into a dark dungeon without a torch. The file was a single 800‑line function called processData . Inside, variables bore names like tmp , x , flag , and comments that tried to explain every line: // TODO: refactor this mess function processData ( input ) { let r = []; // result array for ( let i = 0 ; i < input . length ; i ++ ) { // loop over items if ( input [ i ] > 10 ) { // if value greater than threshold let v = input [ i ] * 2 ; // double it if ( v % 2 === 0 ) { // if even r . push ( v ); // add to result } } } return r ; } I spent three hours tracing why a certain edge case produced an empty array, only to discover the comment “if value greater than threshold” was outdated—the threshold had changed to 12 in a later commit, but the comment never got updated. The code lied, the comments misled, and I felt like a hero who’d just swung at a shadow. That frustration sparked a question: What if we could write code so clear that comments became unnecessary? Not because we’re lazy, but because the code itself tells the story. The Revelation (The Insight) The treasure I uncovered wasn’t a new framework or a slick library—it was a mindset shift: make the code self‑documenting through intention‑revealing names and small, focused functions . When a variable, function, or class name reads like a sentence, the reader can infer what’s happening without a side note. Think of it like reading a well‑written novel. You don’t need footnotes to understand that “She opened the door and stepped into the rain” means she’s going outside. The same principle applies to code: if you name a function filterValuesAboveThreshold , the intent is obvious. Why does this matter? Because comments decay. They become outdated, they get ignored, and they add noise. Self‑explanatory code, on the other hand, stays accurate as long as the name stays accurate. It also forces you to think ab