Infinite coding style arguments; here, global capitalisation
[
Date Prev][
Date Next][
Thread Prev][
Thread Next]
[
Date Index]
[
Thread Index]
- Subject: Infinite coding style arguments; here, global capitalisation
- From: sur-behoffski <sur_behoffski@...>
- Date: 2022年6月23日 10:53:19 +0930
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