Felipe GasperThe ability to express yourself verbally is a useful but oft-overlooked skill for software developers. Here I’m going to explore some guidelines I try to apply in my own writing.
(In the following I’m using incomplete sentences per convention in software status messages.)
DISCLAIMER: I am not a professional writer. YMMV.
1. Avoid “could not”.
Consider this phrase:
Could not open the file “foo”.
This means that, at some point in the (assumedly recent) past, the “speaker”—assumedly some computer somewhere—lacked the ability to open foo.
But does that mean:
1) The computer observed its inability to open foo, and didn’t bother trying?
2) The computer tried, and failed, to open foo?
This is a significant difference, and an important one to disambiguate.
#1 connotes a sense of ongoing inability: “I can’t do this thing, no matter how many times I try.” For example, I can’t jump over my house. No matter how many times I try, it’s just not going to happen. It was also true last night; thus, “last night I couldn’t jump over my house” is a true statement.
#2, by contrast, reports on the result of one specific operation at one specific time. Let’s say I did try last night, for some reason, to jump over my house. This is probably what folks will infer I say “last night I couldn’t jump over my house”, but logically it’s not the only meaning; thus, the statement is imprecise. We can do better.
(Linguistically-minded folks may observe a certain parallel with the distinction between “imperfect” and “preterite” past-tense forms.)
Consider expressions like:
Cannot open the file “foo”.
This connotes ongoing inability, which is the logical way to report cases where, e.g., filesystem permissions impede access to a given resource. (To go back to the house analogy, this would be “I can’t jump over my house.”)
Failed to open the file “foo”.
This states unambiguously that “I tried, but failed.” It doesn’t attempt to communicate ongoing inability; it just gives the outcome of a specific attempt to do something. (Also: “Last night I failed to jump over my house.”)
2. Prefer antonyms over negation.
Consider this phrase:
Not Authorized
We could interpret this at least two ways:
1) I cannot access the resource.
2) I might have access to the resource, but nothing has explicitly authorized me.
While native English speakers may intuitively understand “Not Authorized” to imply meaning #1, a nonnative speaker may not. Logically, either meaning is an accurate interpretation of the phrase.
We can be more precise thus:
Access Forbidden
Sometimes following this principle will lead you to some over-awkward wordings. For example, you could replace …
You do not have a file named “foo”.
… with:
You lack a file named “foo”.
… but that sounds kind of goofy. Depending on context that may be OK, though!
(cf. Strunk & White, The Elements of Style, where it says to ”Put statements in positive form.”)
3. Prefer passive voice to active voice when it makes more sense.
We should prefer active voice to passive voice in most cases: it’s clearer to state that an actor “does” an action, rather than that the action “is done” by the actor.
Oftentimes, though, I find myself describing scenarios where the “doer” is either unknown or irrelevant. In those cases, it’s often more logical to use the passive voice than to contort your phrasing to allow active voice.
Consider the following:
If the file has been opened in the last hour, delete the file.
That “has been opened” is classic passive voice: a form of “to be” plus a past participle. We might try to convert it to active voice thus:
If anyone has opened the file in the last hour, delete the file.
This, though, subtly changes the meaning: now our condition—i.e., the “if block” of our phrase—stipulates a “doer”: “anyone”. It’s a pretty generic expression, but might it lead someone to think that it refers to a person? What if what opens the file is a script?
OK, so we rephrase it again:
If anyone or anything has opened the file in the last hour, delete the file.
This works logically, but to my sense it’s getting a bit awkward. The original passive form of the expression is simpler and clearer.
(cf. Yellowlees Douglas, The Reader’s Brain)
4. Rather than “of”, consider a possessive.
In German, Igor Stravinsky’s “Rite of Spring” is “Frühlingsopfer”: literally “Spring’s Rite”. We wouldn’t say that in English because it just sounds awkward, but in other contexts it can yield a slight gain in concision. Consider these:
the file’s change time
… versus …
the change time of the file
The first one is just a bit more concise.
Another advantage of the possessive form is its “object-oriented” syntax: the word order corresponds to how that might look in code: file.ctime. If your target audience is developers, that might facilitate a bit easier understanding, though it’s subtle enough that they may not notice.
5. Describe causal relationships explicitly.
Compare the following sentences:
You cannot save “foo”. You have exceeded your quota.
You cannot save “foo” because you have exceeded your quota.
Most folks will probably interpret the above phrases the same way, but note that only the second form unambiguously gives the relationship between the two ideas (i.e., inability to save “foo” and quota excess). Being explicit reduces the likelihood of misunderstanding.
Note, however, that the second form includes one larger sentence in lieu of two smaller ones. All things else being equal, longer sentences impede comprehension; thus, one might fear that that loss in comprehensibility outweighs the gain in clarity that “because” yields.
A third option may yield a “happy medium”:
You cannot save “foo”. This is because you have exceeded your quota.
Now there’s more verbiage overall, but we’re back to two small sentences rather than one large one, and we still describe the causal relationship explicitly.
6. Write “properly”.
Like it or not, some people will judge you—maybe even subconsciously—for neglecting widely-accepted grammar conventions. (But hey, that’s life!) Overall, it’s best to avoid that. Learn and apply the difference between “its” and “it’s”, “who” and “whom”, etc.
7. Beware “the”.
“The” is essentially a “global”: it lacks context, which means whatever it references applies universally, unless something else around it restrict scope. Consider:
The submit button doesn’t work.
There are lots of submit buttons in the world … which one do we mean? Assumedly there’d be context around this phrase that restricts it, but as with “could not” above, it’s better to minimize reliance on context. Consider instead, then:
Our login page’s submit button doesn’t work.
8. Avoid “error” as a verb.
“Error”—in American English, anyhow—isn’t a verb. Say “fail” instead—or, if you must, “err”! :)
9. Avoid “not $this because $that”.
Consider this phrase:
I’m not going hiking because of the weather.
All this means is that the phrase “I am hiking because of the weather” is false. Thus, either of these could be what the phrase means:
- It’s too cold for me to go hiking.
- Weather isn’t why I’m hiking; I’m hiking to find buried treasure!
To avoid this ambiguity, do one of the following:
Turn the phrase around: “Because of the weather, I’m not going hiking.”
Express the consequence positively, e.g., “I’m skipping the hiking trip because of the weather.”
What difference does all this really make?
Remember the last time you debugged something that just did not make sense? How many times did you stare at whatever error messages you had, comb through logs looking for clues, or the like? At some point you likely realized that you had misunderstood something—or, at the very least, you spent time wondering if you had.
This is the value of unambiguous messaging. If I see “failed to open the file”, I know an attempt was made to do so; if I just see “could not open the file”, though, I may spend time wondering whether that means an attempt was made, or merely that a stat() revealed improper permissions or ownership.
Unambiguous communication saves time and frustration for you and your colleagues, present and future. What’s not to love about that?
