Tip 2: Practice good comma
gem-editor 120000G0NX Comment (1) Visits (2600)
blog debut and first tip on word order.)Some people live for the moments of rapturous enlightenment when they go "Aha!". Me, I live (or rather, work) for the moments of dazed bewilderment when I go "Huh?". That's my cue that something I'm editing to publish on developerWorks didn't click. Something made me stumble, pause, and wonder what the heck I just read. And then I start reading in reverse, looking for the spot where the sentence derailed.Often the culprit is misused or simply missing punctuation. And more often than not, the punctuation that went awry is the lowly comma.Full disclosure: I adore punctuation. Years ago, a co-worker, a technical writer in my department, observed this and, for my office, made a mobile of punctuation marks and proofreaders' symbols fashioned out of brass rods. I married him. Really. To this day, I see punctuation marks in everyday objects. Behold the orange sweet roll: It's a comma, obviously. So how can you save your reader from stumbling and backtracking--with just the skillful wielding of the comma? I'll show three ways. (I struggled to select just three; the comma is so versatile. To get a fuller sense of its power, I recommend The Well-Tempered Sentence: A Punctuation Handbook for the Innocent, the Eager, and the Doomed.)1. Use a comma in a series
Quick review: In a series of three or more items, the last comma before the "and," "or," or "nor" is called the "serial comma." (developerWorks style calls for the serial comma, as do the leading technical and academic style guides, such as The Chicago Manual of Style, Strunk and White's Elements of Style, and Fowler's Modern English Usage).Pop quiz:
Q: Which is the serial comma in this sentence?
I'm torn between Life, Raisin Bran, and Fruity Pebbles.A: The serial comma follows "Raisin Bran."The serial comma adds clarity by removing ambiguity. Here's an unretouched, comma-challenged sentence I stumbled across:
Make sure that any images, tables or inline frames containing other documents, are less than 550 pixels wide.Huh? Does it mean "tables containing other documents" or just "frames containing other documents"? Let's add the serial comma (and remove an errant comma):
Make sure that any images, tables, or inline frames containing other documents are less than 550 pixels wide.(Less you think me comma happy, as an editor, I've probably removed as many commas as 've added. I refer to this as the law of conservation of commas: In a closed system, the total amount of commas remains constant.)Here's another great sentence that just needs some comma tweaking for first-pass clarity:
At the core of these satellites was a radiation-hardened computing system that was responsible for command and telemetry (a satellite's user interface), power and thermal management and pointing (otherwise known as keeping telephone conversations and television content flowing).Hmmm...how many things was this satellite system responsible for? Was it responsible for power management or just power? To eliminate the ambiguity, let's stick a comma after "management." By doing this, the serial comma clearly delineates the second item in that series as "power and thermal management," with "power" being an adjective here.Here's another example that inspires hesitation:
If you are able to distinguish highlighting, such as color, bold or underscore, you can set the GREP_COLORS environment variable to highlight matches.With rapid reading and without the serial comma, you might think "bold" refers to color, as in a bold color. But then what's an underscore color? Huh? Serial comma to the rescue:
If you are able to distinguish highlighting, such as color, bold, or underscore....Here's another example, but from a newspaper:
The local projects received stimulus funds for research on postmenopausal women practicing yoga, monkeys taking cocaine and elderly people playing computer games, among others.Again, a fast reading might make you wonder just where monkeys are taking elderly people. If I were that paper's editor, I'd add a comma after "cocaine."While the serial comma is standard in technical material like developerWorks', you generally won't see it in newsprint (except where its omission would be even more confusing). Most newspapers and newsmagazines (The New York Times, The Guardian, The Economist) follow the journalistic style advocated by the Associated Press Stylebook and omit the serial comma, most likely for economy of space. Also, in British English, the serial comma is not standard, nor is it in French, German, Italian, and Spanish. But style guides aside: Serial comma usage is often a matter of personal preference and heated debate, among editors, anyway. For example, in the New York Time's blurb here, I think omitting the serial comma is a false economy:
I'd prefer a comma after "law" to save me a second reading. My first reading was "...Arizona immigration law and history...."2. Use a comma to indicate a nonrestrictive phrase
A nonrestrictive phrase, often set off by commas, gives descriptive information that is not essential to the meaning of the sentence.
All of your files, which are in the /ebsvol directory, persist even when the server is down.Meaning: Your files persist. Excellent.
For this task, use a load balancer, which accepts requests and immediately hands them off to the next available application server.Meaning: Use a load balancer.
The parameter simply tells Amazon to launch the instance, which is confirmed in the output.Meaning: The launch is confirmed.Note: Omit the comma if the phrase is restrictive (and use "that"--not "which").
All of your files that are in the /ebsvol directory will persist even when the server is down.Meaning: Your files persist IF they are in that directory; otherwise, all bets are off.
For this task, use a load balancer that accepts requests and immediately hands them off to the next available application server.Meaning: You want a particular load balancer.
The parameter simply tells Amazon to launch the instance that is confirmed in the output.Meaning: That particular instance, the one that is confirmed, is launched.3. Use a comma to indicate a nonrestrictive appositive
An appositive is a word or phrase that follows a noun or pronoun and identifies it.
Session affinity, or session persistence, keeps track of which client was talking to which server.Meaning: By the way, session affinity is also called session persistence. Here, the appositive is nonrestrictive; you could remove it and the meaning of the sentence would remain intact.But when you truly have two distinct things, don't let a comma sneak in. These similar sentences imply different things:
Migrate your application to a cloud environment, using a multitier web application or the trial code available for download.Meaning: You have two choices.
Migrate your application to a cloud environment, using a multitier web application, or the trial code available for download.Meaning: You have one choice; the application is the trial code.Appositives can be tricky in other ways. Consider:
My husband, Jeff, works at Cisco.I have only one husband, so I could omit "Jeff" and the meaning would not be compromised. On the other hand, if I wrote "My husband Jeff," the implication would be that I have some additional husband(s), which would be untrue, not to mention silly since Jeff gave me that punctuation mobile and all.Note: Omit the comma if the appositive is restrictive.
We toured the home of the poet Pablo Neruda.We didn't tour the home of just any poet. No comma is needed.Tip: Here's a little trick I use. Think of the comma as a nick, or perforation, in the sentence. If you could remove the perforated part set off by the comma(s) and still preserve the original meaning, keep the comma(s).Summary: In short, watch your commas; they mean business. The second comma in this sentence wound up costing a Canadian company $2.3 million to renegotiate (at a higher rate) what they thought was an iron-clad, five-year contract.
The agreement “shall continue in force for a period of five years from the date it is made, and thereafter for successive five year terms, unless and until terminated by one year prior notice in writing by either party.”With the comma after "terms," that "unless" phrase applies to the first part of the sentence. So the original five-year contract was cancelled with just one year's notice. Look it up.And finally, this gem from an old Benny Hill sketch shows the difference a comma can make:
What's this thing called love? (an innocuous song title)
What's this thing called, love? (an entirely different question...)