From: Jim Starkey
Date: March 24 2009 8:40pm
Subject: Falcon Coding Style -- The Theory
List-Archive: http://lists.mysql.com/falcon/638
Message-Id: <49C94554.9030808@nimbusdb.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

The coding style used in Falcon is a snapshot of code style that has 
evolved over the years.  The key elements are:

   1. Camel case, classes starting with upper case, variable and methods
      starting with lower case (from Java)
   2. Class encapsulation with a tiny number of exceptions (also from Java)
   3. Vertically aligned brackets (distinctly not from Java)
   4. Indented substatements
   5. Blank lines before and after conditionals and loops
   6. Macros are bad in the absence of a good alternative
   7. Every developer is entitled to 2 goto's per lifetime.  Use them
      sparingly.

The motivation is straightforward.  Falcon is a large complex system 
with strong mechanisms, constructed from a large number of largely 
self-contained classes.  As such, a developer typically scans a lot of a 
code, more code than he or she wants to mentally parse to understand.  
The purpose of the coding style is to enable a developer to quickly scan 
a hunk of code to get the big picture without having to grasp the 
details.  And the big picture is generally a) data structure, and b) 
flow of execution.

A second consideration is something I read two or three decade back, 
which is the most common source of bugs (after typos, of course) is 
convergence to code paths.

Camel case and differential capitalization makes it crystal clear what a 
name represents (the parenthesis is another clue).  Camel case is 
shorter than underscores, and prettier, too.

Class encapsulation is basic software hygiene.  It is a vaccination 
against spaghetti.  It reduces large, hard problems to a series of much 
simpler problems.

Vertically aligned brackets shows code structure without counting 
brackets.  It also allows elimination of unnecessary brackets with 
rendering the code unmaintainable.

Indented substatements make clear the code of statements.  Everything at 
an indented level executes together.

Blank lines before and after conditionals make flow control clear, and 
highlights points of high bug potential.

Things that haven't been addresses consistently are enum and static 
constants.  I've never quite made up my mind.

Relatively recent changes to the style include:

    * I used to put spaces between function name and open paren. 
    * Before Falcon, I didn't skip lines in inner statements.
    * I now use inner class definitions where it makes sense (in Nimbus,
      at least)
    * Falcon puts && and || on the left of a continuation.  I put them
      on the right of continued line.  I just have found a good argument
      to justify this, however.

I don't mind discussing coding style, but I hate arguing about it.  I 
try not to force my style on other people (well, maybe Vlad...), but 
from long, long habit, I almost always do stylistic edits when I'm in a 
module to bring it up to date.  The Netfrastructure code I'm maintain, 
for example, gets frequent module overhauls to bring it up to my current 
practice.  Ditto Nimbus.  There is an argument that stylistic revisions 
confuse a modules's change log.  Probably true.  But the alternative 
leads to unreadable code...

I bring this up now because I'm doing active Falcon coding for the first 
time since I left, and I'm being as hard on you guys as I am on myself.

Final word, guys.  Blank lines are *not* deducted from your salary.  Use 
them for clarity.  
Evenprogrammersusehorizontalblanks.Whyareveritcalblankssodifferent?


-- 
Jim Starkey
President, NimbusDB, Inc.
978 526-1376