One of the most important qualities for effective programming in large codebases is good writing ability—not writing code, but writing prose for other humans.

Undoubtedly, this is not a surprise to long-time industry veterans (after all, we don’t often program in machine code anymore), but it’s a quality I often find is overlooked by engineers that arrive straight out of college. Those that I see write the cleanest, most maintainable code are those who write prose well, whether in documentation, in emails, or in their everyday lives.

Many aphorisms about writing style translate fairly well to coding. Consider the following selection of principles from The Elements of Style by Strunk and White:

• “Place yourself in the background,” and “Do not overwrite.” The best code does its job honestly and without obscuring its meaning with the author’s “style.” If code is so obviously stylized, it is probably written poorly. Exploiting all of the obscure bells and whistles of a language makes for brittle, obscure code.

• “Work from a suitable design.” Plan ahead and make deliberate design choices. Choosing the right architecture makes a huge difference in how cleanly or how tortured your code will read.

• “Revise and rewrite.” Or in the words of Fred Brooks in The Mythical Man-Month: “Plan to throw one away.” Your first solution will take longer than expected, have problems you didn’t foresee, will likely have code put in the wrong places, and have abstractions drawn at the wrong lines. Write a second draft.

• “Use definite, specific, concrete language.” Vague names like lookup_table or callback are useless in much application code. Use more specific, concrete, and informative synonyms like users_by_id or on_success.

• “Omit needless words.” We need not be obscurely terse—we aren’t counting characters for source code anymore—but concise, simple code is best. Use abstractions and language features to remove boilerplate and focus on core logic.

• “Express coordinate ideas in similar form.” Similarity in structure emphasizes similarity in idea, allowing readers to pattern match and understand your code more quickly. Beware, however, the limits to foolish consistency. ¹

• “Keep related words together.” Save your reader from having to jump around different files and switch contexts to follow lines of logic. It is tiring and difficult to do, even with the help of an IDE. Use tools like promises, monads, and other abstractions to write code in linear, readable progressions that would otherwise be fragmented.

• “Prefer the standard to the offbeat.” Be idiomatic. Follow the standard styles of a codebase and language community. Don’t vary for the sake of variance.

And one more aphorism from journalism that I think applies to programming:

• Don’t bury the lede. Document up front. Put public methods and interfaces at the top of a file, not halfway down past implementation details (when possible). Your code should read like a newspaper article: headline to start, the main gist at the beginning, and then more gristly details further down if the reader is hooked and interested.

Still not convinced? See how much of The Swift API Design Guidelines reads like advice for writing prose.