Your Web News in One Place

Help Webnuz

Referal links:

Sign up for GreenGeeks web hosting
July 29, 2021 02:37 am GMT

Prose for Coding Pros

The ability to express yourself verbally is a useful but oft-overlooked skill for software developers. Here Im going to explore some guidelines I try to apply in my own writing.

(In the following Im 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 speakerassumedly some computer somewherelacked the ability to open foo.

But does that mean:

1) The computer observed its inability to open foo, and didnt 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 cant do this thing, no matter how many times I try. For example, I cant jump over my house. No matter how many times I try, its just not going to happen. It was also true last night; thus, last night I couldnt jump over my house is a true statement.

#2, by contrast, reports on the result of one specific operation at one specific time. Lets 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 couldnt jump over my house, but logically its 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 cant jump over my house.)

Failed to open the file foo.

This states unambiguously that I tried, but failed. It doesnt 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: its 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, its 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 conditioni.e., the if block of our phrasestipulates a doer: anyone. Itsa 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 its getting a bit awkward. The original passive form of the expression is simpler and clearer.

(cf. Yellowlees Douglas, The Readers Brain)

4. Rather than of, consider a possessive.

In German, Igor Stravinskys Rite of Spring is Frhlingsopfer: literally Springs Rite. We wouldnt say that in English because it just sounds awkward, but in other contexts it can yield a slight gain in concision. Consider these:

the files 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 its 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 theres more verbiage overall, but were 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 youmaybe even subconsciouslyfor neglecting widely-accepted grammar conventions. (But hey, thats life!) Overall, its best to avoid that. Learn and apply the difference between its and its, who and whom, etc.

What difference does 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 somethingor, 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. Whats not to love about that?


Original Link: https://dev.to/fgasper/prose-for-coding-pros-1ck7

Share this article:    Share on Facebook
View Full Article

Dev To

An online community for sharing and discovering great ideas, having debates, and making friends

More About this Source Visit Dev To