Alan's Style Guide

Prose

• Optimize for clarity.
• Use as few words as possible.
• Avoid contractions (don't, can't, etc.).
• English has a generic transformation from verbs to persons: act -> actor; use -> user; etc. Unless there is context pointing in the opposite direction, the resulting noun has a male grammatical gender, so refer to him and his stuff. Sometimes the person is not derived from this generic transformation, for example participant not participator. In these cases the grammatical gender is neutral.
• Use the Oxford comma.
• Avoid using "this" as a noun. This strategy, this situation, this state of affairs, etc.
• Put foreign phrases (including Latin phrases and acronyms such as e.g.) in italics.

Error messages

• Describe the problem, not how to fix it.
• Focus on the proximate cause.
• Esure the crash site is uniquely identifiable.
• Avoid speculating on uncertain context.

Subjects

• Lowercase everything except names. (Also in German.)
• Keep short.

File names

• Avoid spaces.
• Lowercase everything.
• Use hyphen (-) to separate words.
• Drop genitive apostrophe-ess.

Subtle Semantic Differences

• Verification versus validation. One verifies a claim, or proof, or argument, or supporting data, in order to distinguish truth from falsehood. One validates a protocol message to determine authenticity when said authencitiy is a prerequisite to enter into the next phase of the protocol.
• A car has wheels. A cable car has wheels and is towed up a mountain. A cable cabin is suspended from a cable and offers transport up or down a mountain. A gondola is a small cable cabin.
• Mutation denotes accruing change passively. Modification implies design and intent.
• In due time means: at some point in the future when the dueness is self-evident even though it is not self-evident right now. In contrast, in time means before the time-window expires.

Subtle Spelling Differences

• Trees in the forest, and plants in general, have leaves. Merkle trees have leafs.
• Three or more points that lie on a straight linear are colinear.

Software Development

• Comments describing the purpose of a block of code must be in imperative form and preceded by a line change.
• Traits and interfaces are for reducing the contact surface area of a body of code with its user. Test the interface and not the internal mechanics. (If you need to test the internal mechanics then you have the wrong interface.) Do not write interfaces for the purpose of testing.
• Robust code minimizes context.
• Do not acquire locks in the expression-arguments of a function call; bind it to a variable and drop it afterwards.
• Avoid naming functions after their effect in the caller.

Authorship

• The principal author gets to decide author order.
• Avoid order of magnitude discrepancies in the contributions of co-authors. Drop co-authorship for persons on the low order end.