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
- 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
- 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..."
- "One should note..."
|| Ram Samudrala