I’m in the middle of another round of “Source Code Style Guidelines”, with my co-workers. We know what this means, “Rule One: No Edged Weapons”.

Most of my education has been aimed at science and engineering. Nevertheless, I’ve come to the conclusion that most technically trained people, and especially math majors, are not cut out for programming. This does not mean that their programs don’t work, or aren’t elegant. The problem is more subtle, they simply haven’t the communications skills for it. Program source has few readers, but most programmers assume that their entire audience is the compiler, that piece of software able to parse a programming language, translating program files to machine instructions, a long series of numbers and data which can be executed directly by the computer. At a minimum, most computer programs have these audiences:

  • The compiler, which needs to find the documents perfectly parsable. Do not confuse “perfectly parseable” with “remotely correct”, too often, their union is the empty set.
  • Code reviewers, those dolts who insist upon ignoring your genius, while tediously arguing about comment wording, function names, tab size, and where to go for lunch.
  • The (often) junior programmer who will come behind, commanded to fix your bugs, add features you never envisioned, and generally ruin the elegant masterpiece you checked in last year.

It’s easy and great fun to join in the religious source wars, arguing about angels and pinheads. It’s much harder to remember your readers and actually write for them. With so few reading your code, it is all the more important that every element of style should address these readers, no rule should exist which does not serve them.

The mechanics of programming, of writing source parsable by the compiler can be easily embraced by anyone with a logical mind. Writing about complex ideas and systems for human audiences is a much tougher proposition. Technical writing (and code writing) for humans is so hard to do well that well written code is almost never seen.

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short or avoid all detail and treat subjects only in outline, but that every word tell.

Make the paragraph the unit of composition: one paragraph to each topic
As a rule, begin each paragraph with a topic sentence; end it in conformity with the beginning
Use the active voice
Put statements in positive form
Omit needless words
Avoid a succession of loose sentences
Express co-ordinate ideas in similar form
Keep related words together
In summaries, keep to one tense
Place the emphatic words of a sentence at the end

Oliver Strunk, The Elements of Style 1918

E.B White, adding to the 1935 edition of Strunk’s little book, appended these simple prescriptives:

1. Place yourself in the background.
2. Write in a way that comes naturally.
3. Work from a suitable design.
4. Write with nouns and verbs.
5. Revise and rewrite.
6. Do not overwrite.
7. Do not overstate.
8. Avoid the use of qualifiers.
9. Do not affect a breezy manner.
10. Use orthodox spelling.
11. Do not explain too much.
12. Do not construct awkward adverbs.
13. Make sure the reader knows who is speaking.
14. Avoid fancy words.
15. Do not use dialect unless your ear is good.
16. Be clear.
17. Do not inject opinion.
18. Use figures of speech sparingly.
19. Do not take shortcuts at the cost of clarity.
20. Avoid foreign languages.
21. Prefer the standard to the offbeat.

E.B White, The Elements of Style, 1935

It’s no coincidence that these edicts map almost perfectly to common coding guidelines, “The Elements of Style” has been heavily quoted, sometimes to the point of parody, by hundreds of books on programming. Published in 1974, Kernighan and Plauger’s The Elements of Programming Style might have been the first. While its examples were written in Fortran and PL/1, this seminal book laid out most of the precepts followed to this day. Here’s a few that might seem especially familiar:

“Make your programs read from top to bottom”
“Take care to branch the right way on equality”
“Test input for validity and plausibility”
“Don’t patch bad code – rewrite it”
“Don’t stop with your first draft”
“Modularize. Use subroutines.”
“Each module should do one thing well.”
“Make sure code and comments agree.”
“Don’t over-comment.”

Kernighan and Plauger, The Elements of Programming Style

Kernighan and Plauger did not spend a lot of time on minutia, they were far more concerned with clarity of intent than with placement of braces. Interestingly, in some camps, The Bell Labs C and Unix developers, Thompson, Ritchie, Kernighan and Plauger (Plauger didn’t actually work for Bell) and their many fans, have been accused of ”excessive literacy” It’s hard to say whether this is a swipe from the Mac/Windows point-and-poke crowd, or a swipe at the astonishing illiteracy of so many american engineers (Redmond leaps to mind here.)

For all that the Bell Labs crowd has been accused of excess purity, of being too ”academic”, of style over substance, it’s obvious in retrospect that this was a very pragmatic group of people. They developed solutions that were just good enough, ”The Jersey Approach”, in stark contrast to the ivory tower efforts at MIT, ”The Right Thing”, Which took so long to get right, and then deliver, that the computer science world had gone on without them.

The most important rule cannot be expressed as an element of style, it is “Write literature, write with passion, write to your audience, make your ideas come alive in their minds.” Sadly, this can barely be taught, hardly be learned, and is mostly lost in the rush to publish. And sometimes of course, it’s just hard to be passionate about folding in driver support for the Acme 2100 auto-binding color network printer/copier/scanner, with optional postage meter. Yet such is our lot, so we must gird our loins, and carry our flimsy weapons into battle against the ravening machine.