Monday, May 30, 2016

Developer Echolocation

In addition to psychic debugging, we have developer echolocation.  
When developers emit calls out into the environment (phone system for standup meetings) and listen to the echoes of those calls that return from various objects near them (other developers quoting JIRA issues).

Thursday, May 5, 2016

Wednesday, April 27, 2016

Using the positive form, not the negative form

Recently I posted an image from the European Commission PDF on How to write clearly.

I was asked by a developer colleague:

Is it ever appropriate to use a negative form? (E.g. in negative situations/error cases)

What would be the positive form of something like File not found?

Good question.

What we’re talking about is something called polarity.
  • Affirmative – something is valid
  • Negative – something is false

And typically, you add “not” to make something negative.

The sentences in the incorrect style example from the image I posted creates a string of negatives:

It is not uncommon for applications to be rejected, so do not complain unless you are sure you have not completed yours incorrectly.

It is not uncommon
quite common
Do not complain unless
complain only if
not completed
have completed

Yes, there is one double negative (two negatives in one sentence):  “do not complain unless.” 

(Many languages use double negatives without issue. Russian and Ukrainian are good examples. Even Portuguese.)

But in English, our brain explodes.


So what about the “File not found” example?

We could say: File missing.

But is it really missing? Maybe the file has a different filename than you expect, so it’s not missing, you’re just using the wrong name in the search.

File not found is a nice short sentence. It handles many scenarios: file is actually missing, or the file has a different name, or maybe you didn’t use an adequate search string.

The key is to be clear and to respect the breadth of the problem. In the incorrect style example, it was a string of concepts and tasks using multiple negatives and even one double negative. It wasn’t clear. But File not found is clear because it must handle many scenarios. In an ideal situation, the software would tell the user why the file wasn't found, but that's another issue


How to use the word Comprise


Try to picture the word comprise as a net cast over items or as a giant umbrella protecting individuals from the rain.




It's the big thing that covers individual things.

Correct: A zoo comprises lions, tigers, and elephants.

Incorrect: Lions, tigers, and elephants comprise a zoo.

Maybe you'd be more comfortable using the phrase consists of. You can put that at the beginning of the sentence.

Correct: A zoo consists of lions, tigers, and elephants.

Or if you’re still wanting something at the end of the sentence, use constitutes.

Correct: Lions, tigers, and elephants constitute a zoo.


Incorrect: A zoo is comprised of lions, tigers, and elephants.

Correct: A zoo consists of lions, tigers, and elephants.

Correct: A zoo comprises lions, tigers, and elephants.

Correct: Lions, tigers, and elephants constitute a zoo.

I suspect that people are thinking of “consists of” but use “comprised of,” which is incorrect.