Code conventions
================

Code style and conventions are vital to maintaining code quality over time. This document aims at making them explicit.

Code style
----------

The base is the [Google Javascript Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml), with the following added details or modifications:

- `var` declarations may, and should, be factored (declaring multiple variables with a single `var` keyword).
- Method definitions should be named: `Foo.bar = function bar() { … }` (repeated `bar` after `function`). This allows for easier debugging.
- Modifying prototypes of builtin objects is allowed, and even encouraged through MooTools. We’re not in the browser.
- Method chaining is encouraged, but calls should be split across lines and vertically aligned, like below:

```javascript
	myObject.someCall()
			.someOtherCall()
			.oneLastCall();
```

An [`editorconfig`](http://editorconfig.org) file is provided to automatically configure your editor for this project. [Install a plugin](http://editorconfig.org/#download) if you don't already have it.

An automated style checker is also provided through [`jscs`](https://github.com/mdevils/node-jscs). You can run it with `npm run lint`.

Getters / Setters
-----------------

Getters are mandatory for allowing explicit access to an instance variable. For objects that are not explicitly instantiated from a Class, direct access is allowed.

Object-orientation
------------------

[MooTools](http://mootools.net/) is used to provide an OO layer. **No** explicit prototype access.

Spacing
-------

**Tabs**. Set your converter to 4 spaces if you like.

Spaces allowed and encouraged to precisely align specific instructions, such as:

- multiline conditionals;
- parameters passing split across several lines.

These spaces groups should never be longer than 3 spaces though, and otherwise be replaced with tabs.

Width
-----

There is no max column width. You should use an editor with line wrapping.

This does not mean you should write long lines, quite the contrary: one instruction per line. But that allows you to actually write one instruction per line without worrying about splitting logic.

Documentation
-------------

Document as soon as you’re stabilizing. Non documented code is not considered finished, and will not be merged into the mainline.

Minimal acceptable documentation for a method is all of:

- one-line definition of function effect;
- if applicable, types and possible values of all parameters;
- if applicable, type of and possible values of returned value;
- if any can be raised, exception types and reasons for throwing.

Use [JSdocToolkit tags](https://code.google.com/p/jsdoc-toolkit/wiki/TagReference) with [Markdown](http://daringfireball.net/projects/markdown/) syntax. Follow the [Google Closure annotations reference](https://developers.google.com/closure/compiler/docs/js-for-compiler) for types.

Tests
-----

The goal is to have 100% test coverage. Unless a method is trivial, its acceptance into the mainline will be bound to proper unit test coverage. See [[Development environment]] for details one how to write and execute tests, and check coverage.
