From: Jim Starkey Date: March 24 2009 8:40pm Subject: Falcon Coding Style -- The Theory List-Archive: Message-Id: <> 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