Writing good code and writing good English are a strikingly similar endeavors. We should be able to apply writing advice to code – not perfectly, but on the whole.
These are some of my favorites – I welcome more thoughts and citations in the comments:
- Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
- Never use a long word where a short one will do.
- If it is possible to cut a word out, always cut it out.
- Never use the passive where you can use the active.
- Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
- Break any of these rules sooner than say anything outright barbarous.
…
A scrupulous writer in every sentence that he writes will ask himself at least four questions, thus: What am I trying to say? What words will express it? What image or idiom will make it clearer? Is this image fresh enough to have an effect? And he will probably as himself two more: Could I put it more shortly? Have I said anything that is avoidably ugly?
Orwell, “Politics and the English Language” (a brilliant essay)
To write a genuine, familiar, or truly English style is to write as anyone would speak in common conversation and who had a thorough command or choice of words or who could discourse with ease, force, and perspicuity setting aside all pedantic and oratorical flourishes.
As a general rule, run your pen through every other word you have written, you have no idea what vigor it will give to your style
Sydney Smith
Clarity of writing usually follows clarity of thought. So think what you want to say, then say it as simply as possible.
…
(Selected do’s and do-not’s, summarized)
- Do not be stuffy. Use the language of everyday speech, not that of spokesmen or bureaucrats. Consider rephrasing sentences more pithily and accurately. Avoid, where possible, euphemisms and circumlocutions promoted by interest groups.
- Do not be too pleased with yourself (perhaps akin to Kill Your Darlings)
- Do your best to be lucid. Simple sentences help. Keep complicated constructions and gimmicks to a minimum.
…
Scrupulous writers will also notice that their copy is edited only lightly and is likely to be used. It may even be read.
More resources:
-
Eric Evans’ emphasis on Ubiquitous Language in Domain-Driven Design (book, website, wikipedia) is in the same spirit.
-
Style guides for writers and journalists are good resources, examples are the Economist Style Guide (online, book) quoted from above, and the Chicago Manual of Style (online, book).
-
Steven Pinker’s The Language Instinct is a great starting point for exploring the connection between cognition and language.
-
Chapter 17 of Zen and the Art of Motorcycle Maintenance, which merits its own post…
About the Author
