The best code reads like well-written prose. The best prose reads like well-structured code. Both are about clarity — saying exactly what you mean with no wasted words.
The Hemingway Principle
Hemingway wrote short sentences. He used simple words. He cut ruthlessly.
This works in code too. A function should do one thing. A variable name should say what it holds. A comment should explain why, never what.
If you need a comment to explain what your code does, the code isn’t clear enough. Rename the variable. Extract the function. Make the intent obvious.
Writing as Thinking
Writing isn’t just communication — it’s a thinking tool. When I’m stuck on a technical problem, I write about it. The act of explaining forces you to find the gaps in your understanding.
This is why I believe every developer should:
- Write documentation before code — if you can’t explain it, you don’t understand it
- Name things precisely — naming is design
- Delete more than you add — brevity is a feature
The Editing Pass
First drafts are for getting ideas out. Second drafts are for making them clear. The editing pass is where writing becomes good:
- Remove every word that doesn’t earn its place
- Replace jargon with plain language
- Break long sentences into short ones
- Read it aloud — if you stumble, rewrite
First draft: "In order to facilitate the implementation of..."
Final draft: "To implement..."The same principle applies to code reviews. When reviewing, I ask: could this be simpler without losing meaning?
The Compound Effect
Clear writing compounds. Every well-written commit message saves future debugging time. Every clear README saves onboarding time. Every precise variable name saves code review time.
Write clearly. Your future self will thank you.