OpenLayers Coding Standards

  1. OpenLayers Coding Standards
    1. Writing Code
      1. Style
      2. Conventions
      3. Suggested Reading
      4. Example
    2. Writing Unit Tests
    3. Writing Examples
    4. Committing to Subversion
    5. Managing Tasks in Trac

Writing Code

Style

  • Indent is  K&R style, Variant: 1TBS.
  • Indent four spaces. No tabs! (If you're running vim, set expandtabs.)
  • Variables, properties, and methods are named in camelCase.
  • Classes and namespaces are StudlyCapped.
  • Constants are named in ALL_CAPS.
  • All identifiers should be long enough to be understandable and unambiguous. For example, zoomHasChanged is preferable to zlch. By contrast, lat and lon are sufficient for latitude and longitude properties on the OpenLayers.LonLat class, because they are unambiguous.
  • OpenLayers uses the JSAN standard for laying out source files. Ideally, this means one class per file under lib/, with the file name broken out, one directory level per namespace, e.g. OpenLayers.Layer.WMS -> lib/OpenLayers/Layer/WMS.js.
  • OpenLayers uses Natural Docs style comments to provide info on class, property and methods. See  Natural Docs for information on Natural Docs syntax. Also, read about the Natural Docs conventions in OpenLayers.

Conventions

  • Declare new Objects and Arrays using {} and [] , not new Object() and new Array().
  • When concatenating many/large strings, don't use '+='. Read about this subject in our String Concatenation page.
  • In a for loop, cache the length for potentially large arrays. E.g. for(var i=0, len=long.length; i<len; ++i). This is especially important for long node lists.

Suggested Reading

Example

This is an example of code that you might find in a file named lib/OpenLayers/Pony.js: 

/**
 * Class: OpenLayers.Pony
 * Instances of the Pony class are used to carry small people on rides through
 *     the grass.
 */
OpenLayers.Pony = OpenLayers.Class({
    
    /**
     * APIProperty: color
     * {String} The pony's hair color.  Default is 'brown'.
     */
    color: "brown",
    
    /**
     * Property: capacity
     * {Number} A measure of the pony's current stomach capacity.  Range 0-1
     *     inclusive.  A value of one means the pony is empty.
     */
    capacity: null,
    
    /**
     * Constructor: OpenLayers.Pony
     * Create a brand new pony.
     *
     * Parameters:
     * options - {Object} Optional properties bestowed upon your pony.
     */
    initialize: function(options) {
        OpenLayers.Util.extend(this, options);
        this.options = options;
        this.capacity = 1;
    },
    
    /**
     * APIMethod: eat
     * Give the pony some food.
     *
     * Parameters:
     * food - {Object} The food for your pony to eat.
     *
     * Returns:
     * {Boolean} The pony is still hungry.  If false, your pony has had enough.
     */
    eat: function(food) {
        this.capacity = Math.max(this.capacity - Math.random(), 0);
        return (this.capacity > 0);
    },
    
    CLASS_NAME: "OpenLayers.Pony"
    
});

Writing Unit Tests

  • All the tests for a given class go in tests/test_ClassName.html or tests/test_Class_SubClass.html.
  • When adding a new test file, be sure to list it in tests/list-tests.html.
  • Every change to OpenLayers which exhibits a programatically repeatable behavior should have a test. If you are unable to write a test in the Test.AnotherWay framework, creating an HTML page with step-by-step instructions on how to test the change and including it in the patch is also acceptable.
  • WritingUnitTests tells more about testing with OpenLayers.

Writing Examples

  • Examples should be written to demonstrate use of new API functions/methods or new classes.
  • Examples should be well named (some-class.html or new-method.html) and should have a sensible title.
  • Example markup and code should be separated. Your example HTML page should link to an example JavaScript file (e.g. new-method.html links to new-method.js).
  • Example markup should be standards compliant HTML (no XHTML unless your example requires that specifically). Use <!DOCTYPE HTML> at the top of your markup to trigger standards compliant mode in browsers (see the  HTML5 spec and  this blog post for more detail). This is relevant even if you are not using HTML5 features.
  • Include the <script> tag that pulls in your JavaScript at the end of your <body> element.
  • Examples are all parsed by exampleparser.py to produce an example feed. This example feed serves as the sitemap for our examples and all examples should follow the same conventions as example.html.
    • Link to the default OL stylesheet
    • Link to the examples stylesheet
    • Initialize a global map variable (if creating a single map).
    • Use an h1 element with the id title for your example title.
    • Include a p (or other) element with the id shortdesc that gives a brief description of your example - no additional markup in the shortdesc paragraph.
    • Include more detailed documentation in an element with an id of docs.

Committing to Subversion

  • Be sure all the unit tests in source:/trunk/openlayers/tests/run-tests.html pass before committing to trunk. (If you're committing to your own sandbox, you can break whatever you like.)
  • Each code commit should focus on a single set of changes to the code base. If you make a number of changes to different files for different reasons, please make multiple commits, with a different log message for each.
  • When you commit a fix for a particular ticket, please mention that ticket by number (e.g. #12) in the commit message.
  • Please make your commit logs as verbose as possible!
  • Commits without a commit message will be rejected by SVN.

Managing Tasks in Trac

  • When you start working on a ticket from Trac, be sure to assign that ticket to yourself, so that everyone else knows who's working on it.
  • When you mark a ticket fixed in Trac, be sure to mention the revision(s) (e.g. r73) that contain the fix.

Thank you for contributing to OpenLayers!