One of the annoying fictions of my work is that programming code is written in English. This is affirmation is technically correct (the best kind of correct), but in reality the language used in the code is a very restricted subset of english. When writing, and to a certain extent when reviewing code, I generally use the following principles, some of which are inherited from technical writing, others specific to coding:
- Semi-colons are only used in code, nobody knows how to use them in English.
- Eschew the usage of complex vocables, the demeanour of using convoluted words is jejune.
- Avoid shortened expression with apostrophes, i.e write “This will not…” instead of “This won’t…”. The reason is that depending on the context, i.e. the type of file, of programming language, and within a single language the type of string or comments, the apostrophe needs to be escaped or not, so searching for a message in the code is needlessly complicated. At any rate, English works fine without apostrophes.
- Avoid the use of the saxon genitive, first because its use involves apostrophes, secondly because its usage is less general than using of. One advantage of applying the two rules above is that it avoids the issue of mixing up its and it’s.
- Avoid pronouns. Either repeat the word, or use variable names. Strangely enough, I find single letter variables in text much clear that longer ones; this is probably a leftover from mathematical writing, but I also think this because the context change highlights the variable.
- Avoid synonyms, they add ambiguity, break the search tools, and increase the chances the reader does not know a given word. A cat is always a cat, never a feline. I don’t care what your english teacher said.
- Avoid the Picard Technique. There are a lot of words of latin origin that are technically valid in English, but not widely used except by marketing people and spaceship captains. For instance to say “This commences the thread that utilises the laser interface” as opposed to “This starts the thread that uses the laser interface”. It is a trap! Easy to fall into when one is a native speaker of a latin language like french.
- Function or method names are always followed by opening / closing parentheses, i.e.
- Avoid being smart. Names that are puns, allusions, are very dangerous because they are usually built one some cultural knowledge. While English is the shared language for the code, the various cultures used in English speaking countries are not. In other terms, you can assume the reader of your comments will understand English, but not the vocabulary for gold mining or references to the Simpsons.