General style guide

Idealism runs into pragmatism.

• Acronyms. Always expand out the acronyms the first time and then use the acronym later. Sometimes this may be necessary to do it at the beginning of the major sections, depending on the increased clarity achieved by doing so.
• Attribution. Generally, do not attribute actions to inanimate objects. For example, "Energy flows...". In rare cases it may be acceptable ("Nature has..."), but most of the time it could be rephrased.
• Clarity. Each sentence should be crisp, clear, concise and as near to perfection as possible. This is hard to do without multiple iterations so that's the best strategy for achieving it. Use just the right amount of words, no more no less. This means reading and re-reading again carefully by new sets of eyes, which means giving enough time and making day to day progress (or getting it done earlier than later). This is easier said than done and therefore I think is the most important point I can make.
• Consistency. Ideally, everything should be consistent. In practice, for a consistent style, look, behaviour, and aesthetic, any change can be limited to one modular area (for example, between two "####" in a shell script to perform a stylistic, or one set of files in a directory, or one set of script types). Follow as needed but usually when rushed for time (which is almost every time).
• Headings. Our convention generally is to capitalise only the first letter of heading string, unless there are acronyms or other reasons to capitalise words in the middle. "General Style Guide" is not the correct heading style for this document.
• Hyphenation. Avoid over hyphenating whenever possible. In general, my view is that if something can be written out without hyphenating and it reads well, then it's acceptable (even if there's no such word (currently) in the English language). For example, "non-compliance" should always be written as "noncompliance."
• Typos. Short for "typographical errors", these run the gamut from spelling and grammar mistakes to general forehead smacking verbiage that should be avoided. Careful reading and re-reading by new sets of eyes will help with this.
• Waffling. My PhD mentor John Moult would say "stop waffling" whenever fluffy/vague/awkward/unclear sentences were presented (see clarity above). Examples of waffling to avoid/modify:
  • "In order to..." (can almost always be replaced by "To...")
  • "It is clear..."
  • "Obviously..."
  • "One should note..."