Self-Explaining Code Or Bust

Level 1: A Joke You Have To Explain

This is like telling a joke and then spending five minutes explaining why it was supposed to be funny. The funny part is that code can feel the same way: if someone has to explain every piece before anyone can use it, something about how it was written probably needs fixing.

Level 2: Readable by Humans

Code readability means how easy it is for another person to understand what software is doing. A computer may run confusing code perfectly, but humans have to maintain it, fix it, and extend it. That is why names, structure, comments, and tests matter.

The tweet compares code to humor because both depend on communication. A joke that needs too much explanation loses its effect. Code that needs too much explanation slows everyone down. If a function name is vague, a variable is misleading, or a file does too many things, the reader has to spend extra effort figuring out the intent.

This connects to code quality, maintainability, and technical communication skills. A beginner might think "good code" only means "it works." With experience, "good" also means another developer can safely change it later. Comments can help, but they should usually explain context and reasons, not repeat what the code already says.

Level 3: The Punchline Boundary

The tweet says:

Code is like humor. When you have to explain it, it’s bad.

The joke works because it borrows a rule from comedy and applies it to code readability. If the audience needs a lecture to understand a joke, the timing, setup, or structure probably failed. If a future maintainer needs a walkthrough to understand a function, the naming, decomposition, abstraction, or control flow may have failed. The meme is not really anti-comment; it is anti-forensics.

Experienced developers know the painful version of this aphorism. Bad code often comes with an oral tradition: "Ask Mira before touching that job," "This flag is inverted for historical reasons," "Do not remove that sleep," "The billing service depends on this side effect." At that point, the codebase is no longer communicating through source files; it is communicating through folklore, Slack archaeology, and the one person who is always on vacation when production breaks.

The serious engineering point is that clean code principles are less about elegance and more about reducing coordination cost. Clear names, small functions, explicit boundaries, boring control flow, and well-shaped tests let people make changes without reconstructing the author's entire mental state. When code has to be explained every time, the explanation becomes a hidden dependency. Hidden dependencies are where maintainability goes to lose a weekend.

There is a trap, though. Taken literally, the aphorism can become another way to shame useful documentation. Some things absolutely deserve explanation: business rules, regulatory constraints, performance trade-offs, security assumptions, migration history, and weird compatibility requirements. The best comments do not translate obvious code like count += 1; they explain why the code has to look surprising. Good humor should not need the punchline explained, but good engineering sometimes needs stage directions because production is not a comedy club and the audience rotates every quarter.