It’s been the bane of English students and the bible of creative writing teachers since the second World War. It’s older than you are, meaner than you are, and presumably, built from sterner stuff than you are. This book has survived air-raids and artillery shellings. Its simple lessons of thrift and economy have denuded the world of more bad writing, over the last 70 years, than the shutdown of Google Reader and Geocities combined. That is why The Elements of Style, by William Strunk and E.B. White, is a classic, and that’s why you’ll find a copy of this book (no thicker than the width of your finger) on the “software” section of our bookshelf.
It would be too much to expect that a book written in 1935 could do double-duty as a modern manual of software craftsmanship, but in its 100 pages this book has more to say about the craft of software than many books in the “Computing” section of your local bookstore. A casual search-and-replace for “writing” with “programming” consistently yields paragraphs that might’ve been plucked from Code Complete. Here’s one example:
2.12. Choose a suitable design and hold to it.
A basic structural design underlies every kind of writing programming. Writers Programmers will in part follow this design, in part deviate from it, according to their skills, their needs, and the unexpected events that accompany the act of composition. Writing Programming, to be effective, must follow closely the thoughts of the writer programmer, but not necessarily in the order in which those thoughts occur. This calls for a scheme of procedure….in most cases, planning must be a deliberate prelude to writing programming. The first principle of composition software development, therefore, is to foresee or determine the shape of what is to come and pursue that shape.
The structural similarities between writing and coding are strong enough, and Strunk and White’s treatment of their subject generic enough, that almost anything they say about one is true about the other. Brian Kernighan (of C fame) picked up on these ideas many years ago and wrote a book based on the Strunk and White format: The Elements of Programming Style. What’s remarkable how well the original Strunk & White holds up in a software context. Again, with simple word-replacement:
5.3. Work from a suitable design.
Before beginning to compose develop something, gauge the nature and extent of the enterprise and work from a suitable design. Design informs even the simplest structure, whether of brick and steel or of prose. You raise a pup tent from one sort of vision, a cathedral from another. This does not mean that you must sit with a blueprint always in front of you, merely that you had best anticipate what you are getting into. To compose a laundry list, you can work directly from the pile of soiled garments, ticking them off one by one. But to write a biography, you will need at least a rough scheme; you cannot plunge in blindly and start ticking off after the fact about your subject, less you miss the forest for the trees and there be no end to your labors.
Translation: There’s an appropriate design effort for every project, based on its intended purpose or functionality, and the difficulty or complexity of realizing that purpose. You don’t want to do too little design; equally, you don’t want to do too much. Instead, like Goldilocks, you want to choose the bowl of design porridge which is just right.
5.21. Prefer the standard to the offbeat
Young writers Inexperienced programmers will be drawn at every turn toward eccentricities in language. They will hear the beat of new vocabularies abstractions, the exciting rhythms of special segments of their society industry, each speaking a language of its own. All of us come under the spell of these unsettling drums; the problem for beginners is to listen to them, learn the words, feel the vibrations, and not be carried away.
Translation: Don’t be a hipster. In general, prefer the tried and true to the untried and new, maybe not to the point of becoming a dinosaur, but at least to the point where you don’t piss off your coworkers. A steady diet of normalcy spiced with occasional forays into the new is the best simple policy. And whatever you do, make sure to apply Occam’s Razor, DRY, and KISS liberally:
2.17. Omit needless words code
Vigorous programming is concise. A function should contain no unnecessary statements, a statement no unnecessary expressions, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the programmer make all functions short, or avoid all detail and treat subjects only in outline, but that every line of code tell.
Don’t create things that don’t need to exist. Don’t unnecessarily multiply things. Don’t set up arbitrary divisions between things. Things like: lines of code. Objects. Methods. Enumerations. Components. Excess code exterminates clarity, putting the programmer in an excellent position to violate Strunk and White’s next rule of programming style:
5.16. Be clear.
Clarity is not the prize in writing programming, nor is it always the principle mark of good style. There are occasions when obscurity serves a literary programmer yearning, if not a programming purpose, and there are writers programmers whose mien is more overcast than clear. But since writing programming is communication, clarity can only be a virtue.
Lack of code clarity costs the world billions of dollars a year. It’s the one software sin that management almost never addresses formally because it’s not user-visible and doesn’t affect “the business” and yet…it totally affects the business. At best, messy code acts as an implicit surcharge on every development hour worked. What would normally take you one hour to do, now takes two. At worst, messy code can cause a project to fail, especially where budgets are balanced on a knife’s edge between success and failure. It’s so crucial that the people who come behind you (including the version of you who no longer remembers the code) can understand the code you write, that you could throw out your entire software development playbook and just focus on this one thing and still end up ahead of most programmers. Write bad code, write naïve code, write buggy code if you must. Just write it in such a way that it can be understood.
5.2. Write Program in a way that comes naturally
Program in a way that comes easily and naturally to you, using words and phrases APIs and statements that come readily to hand. But do not assume that because you have acted naturally your product is without flaw.
In order to program in a natural way you have to understand the natural idioms and techniques of the language and toolchain you’re working with. A “natural” coding style, more often than not, is based on long experience with what works, what doesn’t, and how other programmers approach things. It’s not about shooting from the hip. It’s about honing your technicals so that your coding instincts run true.
5.9. Do not affect a breezy manner
The volume of writing source code is enormous, these days, and much of it has a sort of windiness about it, almost as though the author programmer were in a state of euphoria. “Spontaneous me,” sang Whitman, and, in his innocence, let loose the hordes of uninspired scribblers script kiddies who would one day confuse spontaneity with genius.
Give each line of code its due. It’s always cheaper to code things correctly the first time, than it is to code them incorrectly and fix them later. On the other hand, code, like prose, is almost never perfect (or even adequate) in its first incarnation. That’s why it’s important to:
5.5. Revise Refactor and rewrite
Revising is part of writing. Refactoring is part of coding. Few writers programmers are so expert that they can produce what they are after on the first try. Quite often you will discover, on examining the completed work system, that there are serious flaws in the arrangement of the material, calling for transpositions.
If Strunk and White were alive today, they’d probably be big fans of Agile and other iterative, incremental development processes which a) emphasize simplicity and b) allow ample opportunity for stepwise improvement. Of course, we don’t need Agile (or Strunk and White) to tell us that it’s a good idea to:
2.17. Omit needless words code
Vigorous writing programming is concise. A sentence function should contain no unnecessary words code, a paragraph block of code no unnecessary sentences statements, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer programmer make all functions short, or avoid all detail and treat subjects only in outline, but that every word line of code tell.
If there were ever such thing as a universal design criterion, simplicity would be it. And one of the main ways we achieve simplicity is by cutting out the stuff we don’t need. There are times when complexity wins, but generally speaking, the simpler the writing / code / system / work of art, the better. Better because more intelligible; easier to maintain; and structurally more sound.
Young writers programmers often suppose that style is a garnish for the meat of prose code, a sauce by which a dull dish is made palatable. Style has no such separate entity; it is nondetachable, unfilterable. The beginner should approach style warily, realizing that it is an expression of self, and should turn resolutely from all devices that are popularly believed to indicate style — all mannerisms, tricks, adornments. The approach to style is by way of plainness, simplicity, orderliness, sincerity.
Speaking of structure:
2.19. Write Express coordinate ideas in similar form
This principle, that of parallel construction, requires that expressions similar in content and function be outwardly similar. The likeness of form enables the reader to recognize more readily the likeness of content and function.
This is what all of programming aims to do. Of course, too much structure, or “structure for structure’s sake”, can be a Very Bad Thing. If we asked Strunk and White they’d probably say:
5.6. Do not overwrite over-program
Rich, ornate prose code is hard to digest, generally unwholesome, and sometimes nauseating.
Ask yourself, when you’re trying to copy some text from location A to location B, whether it’s better to allocate a chain of distributed Node.js server farms, consult the Registry, set up an eventing hierarchy and spawn a couple dozen worker threads, or, plan B, just use a plain vanilla string copy.
Another good one has to do with, uh, commenting code:
5.11. Do not explain too much.
It is seldom advisable to tell all. Be sparing, for instance, in the use of adverbs code comments…Let the conversation code itself disclose the speaker’s manner or condition coder’s intention.
A good rule of thumb that is often (but not always) correct is that the amount of code comments usually varies inversely with the programmer’s experience level; not because more experienced programmers are more lazy, but because their code is clearer in and of itself. Good code is self-documenting.
Last but not least, one of my favorite elements of style, and what to me is the fundamental rule of surviving a multiple-person development effort:
5.1 Place yourself in the background.
Write Program in a way that draws the reader’s attention to the sense and substance of the writing code, rather than to the mood and temper of the author programmer. If the writing code is solid and good, the mood and temper of the writer programmer will eventually be revealed, and not at the expense of the work.
There’s little to no room for certain types of ego in team-oriented production code. Pride of craftsmanship, yes. Emotional and/or egotistical investment, not so much. Subtract yourself from your code and watch your code improve.