notes on writing code

The best line of code I ever read was a function name. I don't remember what it was, exactly — something in an old Rails codebase — but I remember the feeling. I knew immediately what it did, why it existed, and where it fit.

We talk about "writing code" but rarely take the metaphor seriously. Writing, in the literary sense, is an act of communication with a future reader. The author is always constructing a model of who will encounter these words and what they need to understand.

Code is the same. Every variable name, every abstraction layer, every comment (or pointed absence of one) is a choice about what your future reader — which might be you, six months from now — needs to know.

A few things I've learned:

Clarity over cleverness. The smartest thing you can write is often the dumbest. The one-liner that required you to look up three obscure language features is impressive. It's also a time bomb.

Name things by what they mean, not what they do. getUserData() tells you the mechanism. currentUser() tells you the meaning. The latter ages better.

Comments explain why, not what. The code shows what's happening. The comment should answer: why does it happen this way? What would go wrong if you changed it?

Delete with confidence. Dead code is worse than no code. It creates a false impression of the system's shape. If something isn't used, remove it — that's what version control is for.

Writing is revision. So is coding.