Coding Standards

Owned by Nathan Leiby (Unlicensed)
Last updated: Jul 07, 2012Version comment

Code Style Conventions can be found here: Code Style Conventions for JavaScript

General Coding Standards

  1. We try to enhance readability over magic-wand code. So try to use simple constructs and add enough documentation (Javadoc comments, Wiki page) and unit test for all the code that you write.
  2. Do not mention your author name directly unless required by the convention (liquibase-only). You can be attributed through code commits and modern-day CVS has all the info one needs.

  3. Always copy the license header for ASL 2.0 at the start of each source code page

    /**
 * Copyright 2012, Raxa
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
  4. Declare any string messages or numbers you use as constants (for front end, these constants should go in resources/scripts/Util.js)

Front-End (Sencha Touch and Ext JS) Development

Always:

  1. Always create atleast 1 Jasmine-style BDD test for every function
  2. Always create atleast 1 Jasmine-style BDD test for every single control action
  3. Always define a route for every view you create in ST2/ExtJS. Route and view should have the same name.

  4. Enable CORS headers whenever you are doing Ext.Ajax requests:

    Ext.Ajax.request({
    url: HOST + yourRequestURL,
    withCredentials: true,
    useDefaultXhrHeader: false
});

  5. ...

Recommended:

  1. It is recommended that you use Object literal-style JavaScript class declaration as follows, with a capitalized first-character classname:

    var Foo = {
    type: "fruit",
    color: "red",
    getName: function () {
        return this.color + ' ' + this.type + ' Foo';
    }
}


  2. It is recommended that you place the .json files for in the data folder in the same level as app folder and index.html (as described in Architecting your App)
  3. It is recommended you name your Jasmine spec files in camelCase

  4. It is recommend that you create an enum for the different pages you can navigate to using "setActiveItem", rather than writing setActiveItem(1). This helps with readability and updateability of the code. 

    // Creating enums in JS: http://stackoverflow.com/questions/287903/enums-in-javascript
var <Current Namespace>.PAGES = {
    LOGIN_SCREEN : 0,
    CONNECTION_SETTINGS : 1,
    OPTIONS_PANEL : 2
}

    See how Joy M (Unlicensed) handled this in CHW: https://github.com/jming/Raxa-JSS/blob/f88baa795b560a0972d9e1fc98dcebe5432dc600/src/chw/app/controller/basic.js#L21-28. Note that this code should include the current namespace so as to not conflict with the global namespace.

    See how Piyush Madan (Unlicensed) handled this for Lab: https://github.com/Raxa/Raxa-JSS/blob/master/src/resources/scripts/page_enum.js.


  5. ...

Seldom:

  1. Seldom do z

Never:

  1. Never do w

Back-End Development

Always:

  1. When adding a ChangeSet to the  liquibase.xml file, give your id in the following form:

    <changeSet id="2012-02-29_create_new_feature" author="billclinton">

  2. In the liquibase.xml give a unique constraint name. Keep foreign key constraints separate from createTable changesets. Give constraint names in the following format

    FK_<baseTable>_<columnName>_<referenceTable>_<columnName>
  3. Always use org.raxa.module.<moduleid>... as the package name prefix for modules
  4. ...

 

Recommended:

  1. It is recommended to use _ (underscore) between table names for separate words and camelCase in corresponding Java classes. i.e. if the table is called patient_list, the corresponding class should be called PatientList. Similarly, DAOs should be PatientListDao and implementations of services say PatientListService should be PatientListServiceImpl

  2. It is recommended to use hibernate mappings in your .hbm.xml file rather than Java annotations, so we can read our Java-SQL relationships more easily.

Seldom:

Never:

===============================

Please write suggested coding guidelines below, and we can discuss to determine (1) if we would like to follow the standard and (2) the appropriate level level of enforcement

Suggested coding guidelines: