Miscellaneous

Refactor

Refactor your prose as you would your code:

  • prefer terser expressions where they do not obstruct readability
  • remove duplication, for example, moving repeated phrasing from list items to the list’s preamble
  • find ways to simplify expressions

Mood

Prefer the active mood. For example, prefer

Prefer the active mood.

to

The active mood is to be preferred.

The Complete Plain Words

Numbers

Use words for numbers of things, e.g. “there are three ways to achieve this”, up to a hundred. Use numbers to refer to numbers themselves, e.g. “and adds 2 to the total”.

Place names

Use English place names. Thus Copenhagen not København; Milan not Milano, and Zurich not Zürich.

Using place names correctly in a foreign language is mark of competence. Using them in English is showing off.

Only

Only is a crucial qualifier in documentation. Ensure you place it beside what you intend to qualify.

The reader can usually resolve any ambiguity by eliminating unlikely interpretations. Placing only in the right place relieves her of this work.

The function will only return 0 if an error occurs.

If an error occurs, the function will do nothing but return the result of 0. Otherwise it might also e.g. set 0 as the value of a variable, write 0 to file…

Here only qualifies return.

The function will return only 0 if an error occurs.

If an error occurs, the function returns nothing but a solitary zero. Otherwise it might anything. Including a zero.

Here only qualifies 0.

The function will return 0 only if an error occurs.

If an error occurs the function will return a zero. Otherwise it will return something else.

Here only qualifies if.