-
Notifications
You must be signed in to change notification settings - Fork 7
Code conventions
Code style and conventions are vital to maintaining code quality over time. This document aims at making them explicit.
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 singlevar
keyword). - Method definitions should be named:
Foo.bar = function bar() { … }
(repeatedbar
afterfunction
). 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 are mandatory for allowing explicit access to an instance variable. For objects that are not explicitly instantiated from a Class, direct access is allowed.
MooTools is used to provide an OO layer. No explicit prototype access.
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.
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.
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.
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.