eC Style Conventions

eC Coding Style Conventions
   February 13, 2017 -- Draft version 0.3
=========================================
Identifiers Naming
------------------
- camelCase is used throughout for types and identifiers
- Types (classes/structs, enums...) start with an UpperCase
- Identifiers (global, local, member variables; functions, methods, enumeration values) start with a lowerCase
   - Exception: Previously, Functions/Methods used to start with an UpperCase.
                This was inconsistent and caused various issues, so new convention is lowerCase.
                However, currently Ecere SDK libraries including libecere, libEDA follow the old conventions.
                The next major version of these libraries, breaking compatibility, will adopt the new lowerCase conventions.
                New libraries should all follow the new convention.

Indentation
-----------
   - All code should be properly indented
   - 3 spaces (space characters, not tabs) is used for indenting
   - The indenting style resembles 'Allman style' aka 'BSD style':
      while(!done)
      {
         doThis();
      }
   - switch statements are indented like so:
      switch(value)
      {
         case value1: somethingShort(); break;
         case value2:
            PrintLn("value2!");
            // fall through:
         case value3:
         {
            int variable;
            ...
            break;
         }
      }

Line spacing
------------
   - Extra lines are avoided as much as possible
   - There must be a new line at the end of a source file
   - A single empty line is used to separate methods between themselevs, methods and data member blocks, groups of related data members/variables, functions, classes, logical sections of code
   - 2 empty lines can be used to separate very distinct portions of code
   - There should never ever be more than 2 continuous empty lines anywhere

Comments
--------
   - C++ style single line comments should be used for comments at the end of a line or for a single line of comments
      They're easier to block comment as they do not interfere with multi line comments
   - C style comments should always be used in a block style around multiple lines
   - Don't keep too much unused code around in the form of comments.
     Version control software will keep the old code for you should it ever be needed again.
     Don't be scared to clear up no longer necessary old code.

Warnings
--------
   - Code should be kept warning free. Warnings tend to proliferate and meaningful warnings are lost in a sea of warnings.

Declarations & Statements Blocks, Initializers
----------------------------------------------
   - Declarations are grouped together at the start of a block, then a single line space, then statements follow
   - C89 used to enforce this
   - This makes it very easy to see all declared variables for a given scope all together at the top of the block
   - Variables should be defined at the innermost block where they're required
   - If a new variable is needed later on in a block, a new compound block can be started with { } (and properly indented)
   - Initializers are used as much as possible to try keep as much as possible part of the 'declarations' block,
      e.g.
         int a = calculateSomething();
         float b = calculateSomethingElse(a, 20);

      rather than:
         int a;
         float b;

         a = calculateSomething();
         b = calculateSomethingElse(a, 20);
   - Initializers should not be used if the value a variable is initialized to will never be used
     Great care should be taken however to avoid using uninitialized values, and a 0 initializer should be used if the compiler
     geneates a potentially uninitialized variable warning, even if the programmer knows the value will always be initialized,
     to silence the warning.
   - A single line statement inside a flow control statement will generally not have the superflous compound block curly braces, e.g.:
      if(something)
         doThis();
   - Extra care should be used with if/else constructs, a compound block should always be used if an if contains another if statement,
     to avoid the dangling if problem, e.g.:
      if(something)
      {
         if(somethingElse)
            doThis();
         else
            doThat();
      }

     or:

      if(something)
      {
         if(somethingElse)
            doThis();
      }
      else
         doThat();

   - else if constructs should be written on the same line together, so a single line if statement should never follow an else on the next line either, e.g.:

      if(something)
         doThis();
      else if(somethingElse)
         doThat();
      else
      {
         doSomethingElse();
         doNextThing();
      }

Expressions
-----------
   - Expressions are written as condensed as possible
   - if(variable) is preferred over if(variable == true), if(variable != 0), if(variable != 0.0), if(variable != null)
      - Exception: when structs are passed as parameters, they have an implicit indirection level and if(variable != null) is currently required by the compiler
         e.g.  void doThis(Point a) { if(a != null) { } }
   - if(!variable) is preferred over if(variable == false), if(variable == 0), if(variable == 0.0), if(variable == null)
   - There should not be superfluous parentheses around expressions, unless they clarify confusing operator precendences, such as:
      - Mix of logical || and &&: if((a || b) && c)
      - Ternary conditional operator: (a + b > 4) ? 20 : 30
      - Bitwise operations: (a & b) == true
      - Assignment operators: while((a = doThis())
   - There should be a single space between binary operators and their two operands
   - There should not be space between unary operator and their operand
   - There should not be a space after opening bracket and before closing brackets
   - There should be a space after a , e.g. callSomeMethod(10, 20, 30);  or  x = 20, y = 30;

Instantiations
--------------
   - There should be a space between an instantiation's curly braces and members' initialization
   - Instantiations are written on a single line as part of an expression or declaration if they are short enough, e.g. Point { 10, 20 }
   - If the member ininitialization takes up a lot of space, or if an instance virtual method is being overriden, they should be formatted on multiple lines
      using the Allman style indentation with curly braces starting on new lines, e.g.
      Button button
      {
         this, position = { 100, 20 }, size = { 80, 20 };

         bool NotifyClicked(Button button, int x, int y, Modifiers mods)
         {
            return true;
         }
      };

Use of this
-----------
   - this. is omitted for local members, unless there is a need to differentiate from overshadowing parameters or local variables
   - Overshadowing parameters or local variables should be avoided as much as possible

Function/Method Return points
-----------------------------
   - Ideally, a single return point at the end of the function is preferred
   - Multiple returns statements are okay if they all appear next to each other very close to the end of the function

goto statements
---------------
   - goto is avoided as much a possible
   - If the problem being solved is really, really, really intrinsically difficult to write without a goto, it *may* be okay to use a goto.