William Strunk Jr. and E.B. White, The Elements Of Style, ISBN 020530902X (Fourth edition)
images.amazon.com
Other editions:
Third edition: ISBN 0205191584.
Online Book: www.bartleby.com (The original version by Strunk, which White revised to produce "Strunk And White".)
There appears to be a full, but probably illegal, copy of the new version here: orwell.ru
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 Chicago Manual Of Style.
A must-have reference for anyone who writes... including source code:
Use Active Voice
commands and queries as the "active voice" of object code?
omit needless artifacts, make the code succinct
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
a method should set forth a single idea
Place Yourself in the Background
Egoless Programming for collective code ownership
Keep Related Words Together
if this and that are related to each other, consider putting them together in a proximity such as class, method...
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. Once And Only Once 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 Once And Only Once.
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. Once And Only Once 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 Omit Needless Words, 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. -- Phl Ip
Contains Orwells Parody.
"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." -- Ew Dijkstra
"Any fool can make a rule and any fool will follow it" -- Mark Twain
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 Chicago Manual Of Style, 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: Ten Lessons In Clarity And Grace. If you prefer and can get away with a light approach and are a grammarphobe, try Woe Isi or Sin And Syntax.
First thought this page's about Bringhurst's The Elements Of Typographic Style, the type bible :) ISBN:0881791326
See original on c2.com