On Writing Code That Reads Like Prose

The best code I've read has a quality that's hard to name but easy to recognize: you understand what it's doing before you finish reading it. Not because it's over-commented, but because the structure of the code matches the structure of the problem.

Names matter more than comments. A comment that explains what a function does is usually a sign that the function name was wrong. A well-named function doesn't need explanation.

The right abstraction level. Code should operate at one level of abstraction per function. Mixing high-level business logic with low-level bit manipulation in the same function is like a paragraph that switches between metaphor and literal description mid-sentence. Technically legal. Uncomfortable to read.

Tell the story. The order of operations in code is often the narrative of what the system does. If you find yourself jumping around to understand what a function does, the narrative order is wrong.

The test: can you read the code aloud as if explaining it to someone? If you'd be embarrassed by what you'd say — if it's full of "well, this does this thing for reasons" — the code has more work to do.