Infinite coding style arguments; here, global capitalisation

[sur-behoffski <sur_behoffski@...>]

G'day,

Coding style is a very contentious topic, with different schemes having
vehement proponents and opponents.

So, "Is it a good or bad idea..." will almost certainly be met with a
smorgasbord of responses.

That said, I'll try to make a constructive contribution.  I acknowledge
that others will disagree:  I respect their positions.


--


1. Some background reading:  NASA standards, relating to C coding for
   safety-critical and embedded systems programming, especially featuring
   Gerard Holzmann:

    - NASA JPC C Coding Standards

        https://andrewbanks.com/wp-content/uploads/2019/07/JPL_Coding_Standard_C.pdf

    - The Power of 10: Rules for Developing Safety-Critical Code:

        https://en.m.wikipedia.org/wiki/The_Power_of_10:_Rules_for_Developing_Safety-Critical_Code

    - "Mars Code" presentation by Holzmann at USENIX HotDep '12:

        (Video:)  https://www.youtube.com/watch?v=16dQLBgOwbE
        (Audio:)  https://2459d6dc103cb5933875-c0245c5c937c5dedcca3f1764ecc9b2f.ssl.cf2.rackcdn.com/hotdep12/holzmann.mp3


2. If you're in a project that has a clear, strong, and actively
   enforced coding style, conform exactly to that style.  If the
   project is well-administered, any changes should be subject to
   conformance by the version-control system, and rejected if they
   do not conform.


3. If you're part of a community (e.g. wider set of Lua users),
   then there may be community standards.  Sometimes, these are
   set by the seminal or canonical books on the subject; some
   possibilities is the style in "Programming in Lua", or perhaps
   articles in the wiki:

    - lua-users wiki: Lua Directory

        http://lua-users.org/wiki/LuaDirectory

        (The SampleCode link may demonstrate helpful style hints.)
        (See the lengthy Code Structure / Programming Paradigms section.)

4. Literate Programming

   I'm a fan of Knuth's "Literate Programming", but in a soft,
   non-intrusive fashion, not the particular style that I understand
   he proposed.  In particular, this comes from two observations:

    4.1 MixedCaseCode is more readable than all_lowercase_code or
        ALL_UPPERCASE_CODE.

    4.2 Code is read many, many more times than it is written, so
        optimise for readability.  [I acknowledge that this is more
        influenced by C; in Lua, sometimes dashing off a small,
        stand-alone script, while in the middle of pursuing another
        goal, may be done in a more casual fashion.  However, note
        that sometimes small scripts can grow and can become
        significant entities in a project, so having a conformant
        starting point may be useful.

--


Finally, my private coding style, which I apply to C, which uses a subset
of the Hungarian/CamelCase style:

- Variable names are capitalised, with multi-word names having the
  first letter of each word capitalised:  MultiWordName;

- "Nr" as a short hand for "Number" is handy, either as a prefix
  (NrWidgets  -- total number ), or postfix (SlotNr -- an individual);

- All "LeftValues" -- lvalues -- structs, unions, enums, are strongly
  typed, so adding MS-style type prefix codes is not used;

- I use the prefix "g" to mean "global" -- gModuleContext.  If the
  variable is a pointer, then use "gpModuleContext";

- "p" is one level of reference:  "pObject = &Object;",
  "ppObject = &pObject;", "pObject = *ppObject;".

- I use 8-column indent, and no tab characters unless required
  (e.g. makefiles).  Also, there must be no trailing whitespace.
  This rule helps with content (hash)-based version control systems,
  as there is only one version of the whitespace encoding allowed by
  the coding rules, and this leads to a consistent hash for a file
  that has a conformant layout.

  The 8-column limit is a deliberate pain point that I inflict on
  myself:  As the number of nested constructs increases, the
  potential complexity that the reader has to comprehend increases.
  Splitting deeply-nested code into a separate function makes both
  the parent and the child functions easier to read.


--


While not a definitive answer to your question, I hope that the above
discussion may be helpful, even if it's grown more from C coding than
Lua coding.

cheers,

sur-behoffski (Brenton Hoff)
programmer, Grouse Software