OpenLayers Coding Standards

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 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

• Crockford's  code conventions.
• Elements of Style ( part 1,  part 2).

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.
• 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!