# ArrayFire.js Contributing Guide

## General Rules

Every source file starts with ArrayFire.js' license, which template can be found [there](https://github.com/arrayfire/arrayfire_js/blob/master/LICENSE).

Other rules:

- UTF8
- Max 100 chars per source lines
- Use 4 spaces instead of tabs
- Only English text is allowed
- Don't overuse comments, write clean, good structured code instead
- KISS
- YAGNI
- DRY if it not contradicts with KISS

## C++

### Compiling the native part

ArrayFire.js uses [CMake.js](https://www.npmjs.com/package/cmake-js) of its build system. To build native sources, please install CMake.js from the npm:

```
npm install -g cmake-js
```

Go to ArrayFire.js' source folder, and enter:

```
cmake-js build
```

to build its native addon. You can use `--debug` argument to use debug configuration. 

Enter:

```
cmake-js --help
```

for more information, or refer to its [readme on Github](https://github.com/unbornchikken/cmake-js/blob/master/README.md).

*Notice: It's advised to use an IDE to develop the native module, there is a [tutorial available](https://github.com/unbornchikken/cmake-js/wiki/TUTORIAL-02-Creating-CMake.js-based-native-addons-with-QT-Creator) for instructions of using [Qt Creator](https://www.qt.io/download-open-source/), but other [CMake](http://cmake.org) compatible IDEs will do.*

### C++ Rules

- Language of development is C++11
- Use `auto` everywhere
- File names are written in lower case
- Files are put to `src` directory
- Headers have `.h` extension and use guarding macros
- Source files have `.cpp` extension, and includes `ext.h` at first
- `ext.h` should contain all external includes
- Addon code are put into the global namespace
- Prefer `struct` instead of `class`
- Braces are start on new line
- V8 rules apply for casing and structuring of public code
	- Classes, public members are Pascal cased
	- Functions are Pascal cased
	- Public fields could only accessed by methods
- Internal fields and arguments are lower camel cased, any kind of notation could only used for variables, if required

## JavaScript

### ECMAScript 2015 (aka ES6)

**Language of development is ECMAScript 2015 (aka ES6).** However ES5 is supported by manually compiled code using Gulp. Library's runtime will autodetect if ES6 is available or not and uses appropriate code path for execution. So with io.js and Node.js 0.12 with harmony, ES6 source will run, so it's advised to use those platforms for development to have ability to debug the original code.

To compile ES5 from ES6 first install Gulp from the npm:

```
npm install -g gulp
```

then go to ArrayFire.js' source folder and enter:

```
gulp
```

### JavaScript Rules

- Library's source files are put to `lib/es6` directory
- Unit tests' source files are put to `tests/es6` directory
- Examples' source files are put to `examples/es6` directory
- File names are written in lower camel case
- Standard JS coding rules apply (that every IDE uses as default)
- All source files must pass ESLint and JSHint validation with the included .eslintrc and .jshintrc rules
- New functionality should be covered by unit tests that must pass on atleast two supported HW platforms at your side

## Documentation

### MKDocs

Documentation is generated by [MkDocs](http://www.mkdocs.org/), and its source files put to `documentation` folder. It's not the contributors duty to compile documentation from its sources. However they could see the changes that they are making by [installing mkdocs](http://www.mkdocs.org/#installation), and enter the following command at ArrayFire.js' `documentation` folder:

```
mkdocs serve
```

### Documentation Rules

- All functionality covered by documentation
- Functionality changes have to involve appropriate changes in the documentation also
- All documented functionality refer to appropriate chapter of the [ArrayFire documentation](http://www.arrayfire.com/docs/index.htm) if available