Code conventions

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

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

An editorconfig file is provided to automatically configure your editor for this project. Install a plugin if you don't already have it.

An automated style checker is also provided. 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 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 with Markdown syntax. Follow the Google Closure annotations reference 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.