[Xastir-dev] Proposal to change project coding standards: Please vote!

[Tom Russo]

My votes:
  1) 2 char, space only
  2) Line up braces vertically
  3) Include braces when optional


Discussion below.

On Wed, May 01, 2019 at 08:32:51AM -0700, we recorded a bogon-computron collision of the <curt.we7u at gmail.com> flavor, containing:
> We've been talking in another thread about changing the project coding
> standards, specifically the number of columns to indent and the bracing
> standard.
> 
> Our two relevant Wiki pages are:
> http://xastir.org/index.php/HowTo:Contributing
> and
> http://xastir.org/index.php/HowTo:Developer_Guidelines_and_Notes
> 
> 
> 1) Indents: I originally proposed that we go from 4-column indents to
> 2-character indents (Spaces-only, no tab characters unless required for a
> specific tool). I'm going to back-peddle after reading a bunch of stuff on
> the 'net: People say 4-char indent for C and C++ makes it more readable.
> 
> ***** Please vote on number of chars per indent. *****

Personally, having no particular concern for what is said in "a bunch of stuff 
on the 'net," I find 4-char indentation hideous and unreadable, and I
have *always* struggled with it in Xastir.  Every other project I work on 
requires 2, and I would like us to use 2 as well.

Looking at the Linux indentation style, they want 8 chars (with tabs!), because
they say:

  Now, some people will claim that having 8-character indentations makes the
  code move too far to the right, and makes it hard to read on a 80-character
  terminal screen. The answer to that is that if you need more than 3 levels
  of indentation, you're screwed anyway, and should fix your program.

  In short, 8-char indents make things easier to read, and have the added
  benefit of warning you when you're nesting your functions too deep. Heed 
  that warning.

That's awfully opinionated (it's Linus Torvalds we're talking about, so 
whaddya expect, he's almost as opinionated as I am), and not applicable to 
our code base.  Xastir's got REALLY deep nested code (Linus probably thinks
we're screwed anyway and should fix it), and there's tons of code in enormous
files (like db.c at 19,000 lines) that is mostly on the right half of an
80-column terminal window, and wrapped like crazy.

For a choice example of how far we indent and how hard it can be to read, 
look at "update_messages" in db.c.  Then, for a thrill, go look at 
draw_shapefile_map in map_shp.c.

> 
> 2) Bracing alignment: I prefer lining up the braces vertically which I find
> shows the structure of the code much better.
> 
> We currently use:
> 
>     if (true) {
>         do something;
>     else {
>         do something else;
>     }
> 
> I'm proposing:
> 
>     if (true)
>     {
>         do something;
>     }
>     else
>     {
>         do something else;
>     }
> 
> ***** Please vote whether to line up the braces. *****

I prefer your proposal.  It is also the Linux brace style.  It requires
one more line of Emacs set-up code to enforce, but I already have it in 
my startup file (but it is a command, not a variable, so can't just be
added to the .dir-locals.el file).  That command is 
"(c-set-offset 'substatement-open 0)" to prevent it indenting the braces 
another two spaces (per the "gnu" brace style, which is Emacs' default).

https://www.emacswiki.org/emacs/IndentingC

> 3) Optional bracing: I prefer to include braces when they're optional to
> improve readability. An example case: An "if" statement with one statement
> in the "true" block can be written as:
> 
>     if (true)
>         do something;
> 
> -or-
> 
>     if (true)
>     {
>       do something;
>     }
> 
> I prefer the latter. It's not always immediately obvious what you're doing
> without the braces, particularly when there isn't an "else" clause and/or
> indenting gets messed up.
> 
> ***** Please vote whether to include braces when optional. *****

I'm with you on this one.  Personally, I think that leaving the braces out can 
lead both to readability problems *and* coding errors.

-- 
Tom Russo    KM5VY
Tijeras, NM  

 echo "prpv_a'rfg_cnf_har_cvcr" | sed -e 's/_/ /g' | tr [a-m][n-z] [n-z][a-m]