Apply writing advice to code

December 7, 2008 Pivotal Labs

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.

William Hazlitt

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.

from The Economist Style Guide

More resources:

About the Author


Recent Peer-to-Patent mentions
Recent Peer-to-Patent mentions

Craig Newmark: Peer To Patent: government using social networking "Peer To Patent is Washington's fir...

GitHub post receive hook for Tracker
GitHub post receive hook for Tracker

Chris Bailey wrote a GitHub post receive hook for Tracker, using the API. It's a web service that you run o...

SpringOne 2021

Register Now