CodingStyle

FOAM Coding Style Guidelines

Spacing & Indentation

The FOAM indentation style has only an 'interm' status because it is not the intent that FOAM code be formatted by hand. It doesn't make anymore sense to have a FOAM coding style than it does to have an .xsl (Excel Spreadsheet) coding style. In both cases, it should be the responsibility of the tool to properly create and format the file. If one developer prefers to view the FOAM code formatted with a particular tab width, while another prefers another, this is just a characteristic of the view, just like font face, size, and colours, and shouldn't affect the underlying data-model. This is the normal MVC pattern applied to code.

However, until FOAM transitions over to be fully feature-oriented, has all code Modelled, and stored in DAO(s), the following coding standard will be used.

2 space indents with no tab characters.

Preferred spacing shown below, but is optional if you have your editor configured to work with the regular Google coding style.

for ( var i = 0 ; i < SIZE ; i++ ) {

}

if ( condition ) {

}

if ( ! condition ) {

}

if ( condition ) {
  // code here
} else {
  // code here
}

var x = condition ? value1 : value2;

function f(a, b, c) {
  ...
}

f(a, b, c);

var a = 42;

Comments

User documentation should be modelled rather than appear as Javascript comments. This is so that documentation can be easily searched via DAO queriers and made available and searchable in the FOAM Modeller.

Type declarations should be modelled rather than relying on comment annotations. This is so that type information can be easily searched via DAO queries, made available and searchable in the FOAM Modeller, and be used for type-checking.

Naming

• Model names should be capitalized camelCase. Ex. Model, Photo, EMail.
• Acronyms should have all letters capitalized: Ex. DAO
• Properties should start with a lower-case character and be camelCase. Ex. parent, firstName
• Non-public properties and methods can end with an underscore (_). Ex. listeners_
• Use NAMES_LIKE_THIS for constant values.

Modelling

All code should be modelled rather than created as conventional JS prototypes. There currently exists some non-modelled code in the FOAM code-base, but this code is being converted.

Provide property labels when the default labelization of the property name will not be helpful or attractive to users.

If a model has more properties than can be effectively displayed in a TableView, then define its tableProperties to select the most important fields.

Line Length

Line lengths should be 80 characters or less, except for embedded data, like templates or sprites, or when modifying the code to make it fit in less than 80 characters would actually makes it less readable.

Other

• Do not quote map keys unless necessary.
• Do not leave trailing unnecessary commas.
• Except where noted below, FOAM conforms to the Google Javascript Styleguide available at:

http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml

Exceptions

• Constants: Use the constant feature rather than @const.
• Multi-level prototype hierarchies: Yes, but provided by FOAM
• Method and property definitions: use Models instead
• eval(): Yes, but use FOAM's version which works from whithin packaged-apps
• with() {}: Yes, is needed for scope/context management
• Multiline string literals: use FOAM templates
• Modifying prototypes of builtin objects: Yes, but with extreme care
• Visibility (private and protected fields): Do not use JSDoc annotations.
• JavaScript Types: Include in models instead.
• Providing Dependencies With goog.provide: No, use Model imports and exports (when available).