Sunday, June 25, 2017

Using Commas - Part Two

In this continuation from the previous lesson, we will dig deeper into using commas in technical writing.

Avoiding the comma splice 

A "comma splice" is the incorrect usage of a comma to separate two independent clauses. (Reminder: an independent clause has both a subject and a verb.) For example:

The server has started, you can log in.

The first clause has the subject "The server" and the compound verb "has started". The second clause has the subject "you" and the compound verb "can log in". Therefore, they are both independent clauses.

When there are two independent clauses, you can separate them in the following ways:
  • Use a period if they stand alone as separate ideas: The server has started. Log in using your credentials.
  • Use a comma and a conjunction if they are connected ideas: The server has started, and you can now log in.
  • Use a semicolon if they are closely-related ideas: The server has started; you can log in.
(You could also use dashes, but we won't cover that until the next lesson.)

Semicolons can lead to long and somewhat ambiguous sentences, so we tend to avoid semicolons in technical writing. It's better to create two separate sentences with a period, or use a comma and a conjunction that clearly shows how the ideas are connected. For example, consider this sentence:

The server is starting; you can log in now.

Does this mean you can log in because the server is starting or in spite of the fact that it's still starting up? A comma and conjunction make the two different meanings clearer:

The server is starting, so you can log in now.
The server is starting, but you can log in now.

Using commas with adverbs

An adverb modifies a verb, an adjective, or another adverb. They often end in "-ly", which makes them easier to spot. For example:

He ran swiftly. 
("swiftly" is the adverb modifying the verb "ran")

The really fast connection made surfing the web a lot more fun. 
("really" is the adverb modifying the adjective "fast", which is modifying the noun "connection")

He ran incredibly swiftly. 
("incredibly" is the adverb modifying the adverb "swiftly", which modifies the verb "ran")

As you can see, you do not use commas between adverbs and the words they modify. The exception is when you repeat an adverb for emphasis, such as: 

The really, really fast connection made surfing the web a lot more fun.

But don't do this in technical writing, please!

Put the adverb as close to the word it modifies as possible. For example, "Swiftly he ran" is fine in poetry, but it sounds awkward in technical writing. Worse, moving the adverb away from the word it's modifying can also create confusion in more complex sentences. An exception is when you put it at the end of an imperative (command) sentence to add emphasis:

Return to the front desk immediately.

You could also write "Immediately return to the front desk", but it sounds more like a general instruction and less like an urgent command. 

This brings us to sentence adverbs, which usually do appear at the beginning of the sentence and are followed by a comma. A sentence adverb modifies the sentence as a whole instead of a specific word. It is useful for expressing an opinion. For example:

Incidentally, your father dropped by earlier.
Sadly, the ball was canceled.

When I write these sentences, I'm expressing the opinion that the information I'm giving you about your father stopping by is an incidental aside, and I'm expressing sorrow that the ball was canceled. You can also put sentence adverbs in the middle or end of the sentence to put less emphasis on them:

Your father, incidentally, dropped by earlier.
The ball was canceled, sadly.

Notice that wherever you put the sentence adverb, it's always separated from the rest of the sentence by commas.

Using commas with imperatives

An imperative is a command, such as "Type your password at the prompt." The implied subject of this sentence is "You", and the verb is "type", so it is an independent clause. Even the one-word sentence "Go!" is an independent clause, because the subject ("You") is implied.

When you have two imperatives whose ideas are closely related, even though they are independent clauses, you don't need a comma between them. For example:

Type your password and press Enter.
Change the Foo property to BAR and click OK.

If the second clause is long, or if it is more of a separate step, you can use a comma. To avoid confusion, I often insert the word "then" when I'm using a comma and conjunction between imperatives. For example:

Change the Foo property to BAR, and then select the action type. 


You might be wondering why we have all these rules for commas. In technical writing, our goal is to get the information as quickly and accurately as possible into the reader's brain, and using commas correctly helps a lot. Just remember that even if a sentence is punctuated correctly, you must rewrite it if it violates the hiccup rule

In the next lesson, we will cover hyphens and dashes. 

Additional resources

No comments:

Post a Comment