Humor

Every once and a while I wander back to defprogramming.com to see what comes up. Today I got

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

Which I really like. Because code should be obvious when you read it. That doesn’t mean what to write is obvious. Far from it. The problem you’re trying to solve is nuanced. It’s complex. There are lots of corner cases to odel with. I get that.

But the resulting code shouldn’t be complex. It may be detailed, but it should be easy to understand and easy to explain. There shouldn’t be unintended side-effects, and there shouldn’t be unexpected requirements.

Or, to put it differently, yes, you should be commenting your code, but your comments shouldn’t be to describe what the code is doing. What the code does and how it does it should be obvious from reading it. Instead, your comments should be about why you’ve chose to do it that way. What were the constraints? What didn’t work and why? If there’s an extension that seems obvious but won’t work, explain why before someone tries and it doesn’t work.

Because cognitive load. Remember, how you write your code isn’t for the computer. The compiler/interpreter is going to take what you write and turn it into something the machine understands. Don’t worry about that part. The part you need to worry about is the next person to look at the code. Make it easy for them to understand. Otherwise you’re going to get paged in the middle of the night when something goes wrong. And no-one wants that.