A Sense of Style

Observer basic style rules such as:

• Well-chosen class and feature names. Underscores, not CamelCase.
• Standard case convention (MY_CLASS, my_feature). (I still use first-upper-case for constants and onces representing shared objects, e.g. Avogadro, Error_window, but many people have shed that convention, and it is really optional – the others are not).
• Proper use of tabs, spaces (before but not after an opening parenthesis, not before a closing parenthesis, before and after operators such as + and = ) etc.
• Presence of header comments. No routine ever without a header comment.
• Style of header comments. Should be terse (usually no need for articles, native speakers of Slavic languages welcome.) Every single argument of a routine should be named in the header comment, between a back quote and a normal quote. Every single one. For example, with display (v: T; f: FORMAT_SPECIFICATION), not “Display value with given format” but “Output `v’ using format `f’”.
• Also for header comments, avoid repeating information that is already visible in the interface (contract view): use different words when it helps (“Output” if the feature name is `display’).
• In these comments, usually no need to repeat what is already in the precondition, but there can be exceptions for emphasis (e.g. if the precondition says not t.has (x) the comment can still say “this routine is only applicable to x not already present; [New Line] For always applicable version, see `other_routine’”. This adds information not immediately derivable from the rest of the interface, by pointing to another routine.
• Always fill `description’ note entries at the beginning of the class (or at the end for long entries, with a pointer at the beginning). Use multi-line (Verbatim) strings if necessary.
• No need to end lines with semicolons (except in rare cases of syntactic ambiguity).
• One instruction per line, although personally I write short conditionals on a single line, e.g. “if not t.is_empty then print (t) end”, for which 5 lines is a waste.
• Any comment includes the nature of the problem that may have to be fixed, who wrote the comment, and when. (Better of course to have no such comment.)
• Judicious use of parentheses when the precedence rules are not obvious, e.g. (a and b) or (c and d) for clarity. No need for superfluous C-style parentheses in conditionals: just if a = b then…

For variable naming, the following has been suggested:

• a_var — feature arguments with exceptions for easily understood arguments like `i' or `x' or `y' (i.e. counters or typical math symbols).
• l_var — local variables with same exceptions as rgument variables
• ic_var — across-loop ITERATION_CURSORs
• al_var — attachment tests where a local is needed (i.e. if attached {STRING} l_my_string as al_my_string then … end)
• t_var — some instances of named-TUPLE-items, where one needs to be reminded in places beyond where the TUPLE is defined that the object is in fact a TUPLE, and not a typical class with attribute features. This “coding standard” rule for me is squishy.
• Style Guidelines