William Strunk Jr. and E.B. White, TheElementsOfStyle
, ISBN 020530902X
The Old Reliable. If you write C++, you need the ARM; if you write English, you need Strunk and White:
- It's short: ninety-one pages in my edition.
- It's authoritative. No shilly-shallying about what some people think; Strunk and White lay down the law. For instance, I was trying to decide whether to put a comma after "Strunk". See p. 3: "James Wright Jr.", preceded by a discussion of the use of commas to surround parenthetic remarks.
- It hits most of the sore spots in writing English. Not sure whether to use "that" or "which"? Worried about splitting an infinitive? Unsure about "hopefully"? Strunk and White will straighten you out.
- It's incredibly terse, yet witty. "Interesting. An unconvincing word; avoid it as a means of introduction. Instead of announcing that what you are about to tell is interesting, make it so."
Having said all that... I usually consult the ChicagoManualOfStyle
A must-have reference for anyone who writes... including source code
- Use Active Voice
- Use Parallel Construction on Parallel Concepts
- originally "Express Coordinate Ideas in Similar Form" (except that's not parallel ;-))
- if the semantics is similar, let the form be similar, too
- Make the paragraph the unit of composition
- Place Yourself in the Background
- Keep Related Words Together
The parallel between writing in natural languages and writing code will go only so far, and we're already past that boundary in this page. OnceAndOnlyOnce
does not apply to writing. A computer will understand what you tell it the first time; it can (and usually does) take more than one repetition to get an idea across to a person. In code, "Parallel Construction" will probably be at odds with OnceAndOnlyOnce
Having the computer understand is not a big problem, but letting people understand is the problem. Therefore, if two pieces are similar in the semantics, it could be preferable for them to be similar in the form as well, so that people could understand the intention and the semantics easily.
For both code and prose, if there are two fragments with similar meaning, there's a good chance that the common aspects can be factored out to a separate fragment. When dealing with prose, getting the meaning across is more important than eliminating the redundancy. When dealing with code, the reverse obtains.
I can't agree with you more. OnceAndOnlyOnce is not a rule to abide by consistently when it comes to prose - because it is rare a case that they'll be reused. However, there is OmitNeedlessWords, which at the first sight could seem like contradicting with "for the sake of understanding you may repeat yourself." What matters is dynamically finding the optimum point somewhere between and beyond "economics and efficacy" dilemma, towards the ultimate goal of understanding whether it be of computers or humans, or both. Yet, in the case of codes especially, yet another goal, without breaking the understandability goal, might come in, "reusability and modifiability", which makes the situation more complex.
"Omit Needless Words" does not mean that prose be sparse or incomplete, but that every word tell. Sometimes in prose you must tell something twice.
The point is not to find direct parallels between Strunk & White's prose style elements and coding style elements (though that's fun and useful). The point is to learn good style in general, so that we may better identify such when it turns up in the code. -- PhlIp
"It is impossible to sharpen a pencil with a blunt ax. It is equally vain to try to do it with ten blunt axes instead." -- EwDijkstra
"Any fool can make a rule and any fool will follow it" -- MarkTwain
I wonder if the preceding are supporting or countering EoS. :)
Being who I am I must chime in. While Strunk & White is certainly complete it's not my favorite usage/grammar book, even though the analogy in the introduction about a writer's task being akin to getting someone safely through a swamp is quite nice. It's rubbed me wrong from the beginning. I too would recommend ChicagoManualOfStyle
, or simply Chicago as people tend to refer to it, however it is a monstrous, hardcover beast, still a useful, monstrous, hardcover beast, and bright orange to boot. I also like Style: TenLessonsInClarityAndGrace
. If you prefer and can get away with a light approach and are a grammarphobe, try WoeIsi
First thought this page's about Bringhurst's TheElementsOfTypographicStyle?
, the type bible :) ISBN 0881791326