One of the biggest differences between writing code for machines and writing English-language text for humans in the United States is the use of quotation marks. When you’re programming a computer a set of double quotation marks indicates a string, which is an atomic entity. As such, punctuation goes outside the quotes to delimit lists and whatnot.
#include <stdlib.h>
string animals[4] = {"Goat","Sheep","Cow","Platypus"};
This is not how it works when you’re writing in the English language. Periods and commas always go inside the double quotation marks in English.
Incorrectly punctuated sarcasm: We all know how that piece of software “works”.
Correctly punctuated sarcasm: We all know how that piece of software “works.”
Incorrect: Her number is “867-5309”.
Correct: Her number is “867-5309.”
Question and exclamation marks go inside the double quotation marks, too.
Incorrect: “What the hell are you doing to that hard disk”? he said.
Correct: “What the hell are you doing to that hard disk?” he said.
Incorrect: “Don’t press the EPO button in the data center”! he screamed.
Correct: “Don’t press the EPO button in the data center!” he screamed.
Instead of a period use a comma inside the quotes:
Incorrect: “I simply asked him why he was in his underwear and there was 1000 feet of unspooled fiber on the floor”, Joe said quietly to the HR representative.
Correct: “I simply asked him why he was in his underwear and there was 1000 feet of unspooled fiber on the floor,” Joe said quietly to the HR representative.
Yes, this presents problems sometimes. Sometimes you want to denote that something is a string, or spelled a particular way, and don’t want to misconstrue that the punctuation is part of it. For me this usually happens with server names.
Grammatically incorrect: We need to fix the fans on servers “esx-1-goat-4”, “esx-1-goat-10”, and “hosebeast”.
You have several ways to tackle this without running afoul of the pedantic grammar Nazis.
Capital letters: We need to fix the fans on servers ESX-1-GOAT-4, ESX-1-GOAT-10, and HOSEBEAST.
Italics: We need to fix the fans on servers esx-1-goat-4, esx-1-goat-10, and hosebeast.
Bold: We need to fix the fans on servers esx-1-goat-4, esx-1-goat-10, and hosebeast.
A list works, too.
We need to fix the fans on the following servers:
- esx-1-goat-4
- esx-1-goat-10
- hosebeast
My favorite is caps. Easy to read, gets the point across, looks like a normal paragraph. Be creative, but ask yourself how you can write it so your meaning is crystal clear to the reader.
In conclusion, y’all are really freaking smart, yet I see you all making this mistake all the time. English is just another programming language, except you’re getting humans to do your bidding instead of a machine. Consider this a compiler warning. 🙂
P.S. I explicitly mention the English language & U.S.A. just because I don’t know the rules in other languages. I’m guessing that in many cases the rules are the same. Leave a comment if they aren’t (or if I’ve missed something here, like always).
P.P.S. I’ve been informed — several times — that “proper” English, aka that which is spoken in the United Kingdom, has this all backwards, including using single quotes where Americans use double and vice-versa, putting all manner of punctuation outside the quotes, etc. Of course, the Americans are the ones with it backwards. 🙂 Do what you want but in the U.S.A. it’s a grammatical error.
Another article in the long litany of articles about English usage. It’s ironic that you say “English is spoken in the UK, too”, because http://www.catb.org/~esr/jargon/html/writing-style.html has said for quite a while now that an Oxford writers dictionary prescribes the hackish way of doing things. The hacker way is just as accepted as the US way. It’s not coincidence that the cited Oxford dictionary calls the hackish way “logical”, either.
Yes, because ESR is the authority on writing (perhaps self appointed, like everything else).
Thanks for writing this one. I try to abide by this rule on all my posts even though it looks weird. If you catch any errors, let me know “and I’ll correct them.” 😉
🙂 And thanks for writing as well, super helpful, unlike all this useless grammar crap. 🙂
There are language prescriptivists and descriptivists. I’m a descriptivist. The American style of punctuation is just that, a style; and one that is not shared by our cousins overseas. It’s not some natural law like gravity or sock-eating dryers. Putting punctuation inside quotes reduces ambiguity, especially when dealing with technical terms. Many seem to find that useful. What’s the harm? Who are we betraying except the third-grade teacher in our minds?
p.s. For the same reason of reducing ambiguity I am for the Oxford Comma as well, although it is also disallowed in many American style guides.
p.p.s. Steven Pinker agrees with ESR on this: http://www.theatlantic.com/entertainment/archive/2014/12/steven-pinker-interview/384092/
To explain my ESR feelings, my eyes want to roll anytime someone references ESR. Perhaps it was his writings about & during the Brendan Eich/Mozilla kerfluffle that put me over the top. Perhaps it’s my personal quest to be less of a pedantic know-it-all that makes him blaze hot red to me as the global messiah of know-it-alls. Regardless, I have a serious aversion to him now. If you’ve ever read Gibson’s “Pattern Recognition” I liken these thoughts to the reaction that Cayce Pollard has to corporate branding, almost allergic in nature.
While I’m off topic, I was folding socks at the moment my phone buzzed to tell me of your comment. Three adult unmatched socks — WTF. Two kid unmatched — standard, their mate could be anywhere. If you’re stalking me knock it off and come inside for a drink, it’s 10° F outside.
ANYHOW, with regard to ambiguity you’re dead on, we should always strive to reduce the ways in which a reader could perceive our writings. That’s the core of my point, especially with documentation and email. If that means a rule violation I’m all for it, but the end should justify the means, and we should get some sort of net gain from the rule violation. Clarity is a great thing to gain.
I’m split between Scott Porch and Steven Pinker. That is a great article, and Porch echos many of my own thoughts (whether they’re his or he’s just taking a contrary view for the interview we won’t know). What I don’t like is that Pinker seems inconsistent. In particular, his commentary on punctuation outside the quotes:
“Messing up the order of delimiters in a way that doesn’t reflect the logical nesting of their content is just an affront to an orderly mind.”
doesn’t jive with his later saying that “[a] rule is not a rule in the first place.” Sure, English isn’t XML, which I agree completely with (I can’t say what I said and not agree). And fine, rules aren’t rules. So they’re design patterns. But don’t insult me by saying I don’t have an orderly mind when you also said I could do whatever the hell I want. My orderly mind says “up yours, Pinker.”
Still, so few people know the written design patterns/rules of their primary language. It’s one thing if you know the rule and choose to break it, it’s another thing if you have no idea what you’re doing in the first place. I blame this equally on students, parents, and educational systems. We’re not betraying our third grade teacher when we ignore all language standards. We’re betraying all the people that have been suckered into reading poorly constructed & moderately illegible email, documents, presentations, blog posts, et cetera. We’re betraying all the people we could have helped in the time we spent trying to figure out what the hell someone was trying to tell us, or redoing work because the specification was horrible. What’s the harm? Nothing major, just constant, nagging drags on our time, talent, and emotions, will to live, etc. 🙂
I guess in the end I don’t really care what people do, just that they pick a valid style and use it properly. The style I’d recommend would be that which is most commonly used among the people they will communicate with. I’d like them to remember that they have typeface and formatting options for adding clarity. And last, if they choose to deviate from that style’s rules they do so not just out of apathy & ignorance but to gain something, such as clarity or humor or being able to get a message inside 140 characters.
I’d also ask that society stop letting people off the hook for their ignorance, and that, as a species, we strive to be better at the things we do, but I am pushing my luck already.
Oh, and Oxford comma all the way. Nearly every style guide calls for use of the serial comma. Except, of course, the AP and New York Times stylebooks. Exactly why do journalists want to add ambiguity to their work? Squirrelly, imprecise bastards. Perhaps when newspapers finally die we can bury their stylebooks with them. 🙂
Agree on ESR. And on clear writing, especially for technical folks.
I would just ignore the convention, and intentionally write the:
” ‘esx-1-goat-4’, ‘esx-1-goat-10’, and ‘hosebeast’ ”
The ruling principal is that getting the message across efficiently, clearly and unambiguously is more important than meeting idealized language style traditions.
Also, the usage of the names in the text is like that in a programming language.
Where quotations would appear in normal English usage, a word or phrase being quoted — in ordinary English prose there would be no need to use quotation marks for the purpose of showing the exact sequence of characters representing a string inclusive of punctuation.
This is a special case, and technical writings have some unique requirements that should be honored more than earlier traditions.
There is a subtle but important difference for the reason of the quoted object being included in the first place, and since putting the extraneous punctuation inside the boundary of the quotes can defeat that purpose, it ought to be avoided.
In this case, you can think of the quotation marks as a foreign language blob being inserted, which follows the conventions we are familiar with from Perl or C.
And further imagine the punctuation mark would have a special meaning in the language that would cause a great misunderstanding if placed there,
because that is essentially what we have.