JavaScript — Libraries and guidelines/code style

Most of our UIs are developed in JavaScript using the ExtJS4 framework from Secha (http://sencha.com).

Libraries

At the time of writing, we only use ExtJS4. We are open to including more libraries, but we have not had the need yet.

Guidelines and code style

Indent

4 spaces

Naming

Real meaningful names like:

var age = 10;
var username_to_name_map = {peterpan: 'Peter', wendy: 'Wendy'};

NOT:

var a = 10;
var u = {peterpan: 'Peter', wendy: 'Wendy'};
var usrmap = {peterpan: 'Peter', wendy: 'Wendy'};
Private methods and functions

Same format as semi-private python methods/functions (prefix by _):

_my_private_method: function() {
    return null;
}
Code format

Should pass without any errors from JSHint (see JSHint).

Code layout

The ExtJS app layout. See the devilry_subjectadmin app and the ExtJS4 docs.

Documentation

Use the JSDuck format (https://github.com/senchalabs/jsduck). Note that you do not have to document every single function, but you should at least document:

  • Functions, methods and variables used outside its context (I.E.: you do not have to document view-functions that is only used by its controller, but you have to document it of multiple controllers use it).

  • Properties and config parameters for ExtJS classes.

  • Events for ExtJS classes, especially if they are used outside their controller.

File naming

Name controllers by what the control (E.g: controller/period/PeriodController.js), and the views after their purpose (E.g.: view/period/PeriodOverview.js). Try to use unique names instead of generic names like Overview.js. To see why, try to find (quick open) a file with tens of matches in an IDE like PyCharm or Eclipse that only search for file names, not for folder names (hint: it is not quick to open such files). We learned this when developing devilry_subjectadmin with controllers and views named Overview.js.

JSHint

For info about JSHint, see http://www.jshint.com/.

Install

Install NodeJS and Node Package Manager (part of NodeJS):

  • Ubuntu: sudo apt-get install nodejs npm

  • OSX with homebrew: brew install npm

  • Others, see: http://nodejs.org/

Install JSHint in /usr/local on most nix systems, like Linux and OSX:

$ sudo npm install jshint -g

Usage

Simply point JSHint at a directory:

$ jshint src/devilry_subjectadmin/devilry_subjectadmin/static/devilry_subjectadmin/app/

The defaults are sane (unlike JSLint), so you should not need to supply any options.

Building the ExtJS javascript apps

Note

This is only needed if you have made changes to javascript sources, or if you are making your own ExtJS app.

Dependencies

You need to install Sencha tools 2 to build the ExtJS javascript apps. Sencha tools requires an Oracle Java Runtime Environment.

The tasks

Use one of the jsbuild task. Use bin/fab -d jsbuild for docs. Example:

$ cd devenv/
$ bin/fab jsbuild:devilry_subjectadmin

To build without compressing the JS-sources (for debugging):

$ cd devenv/
$ bin/fab jsbuild:devilry_subjectadmin,nocompress=true

Watch the filesystem for changes and rebuild

Call the tasks with watch=true. E.g.:

$ cd devenv/
$ bin/fab jsbuild:devilry_subjectadmin,nocompress=true,watch=true

You probably want to use:

$ cd devenv/
$ bin/fab jsbuild:devilry_subjectadmin,nocompress=true,watch=true,no_jsbcreate=next

to create a JSB-file on startup, but no on each watcher-trigger. This speeds up rebuild significantly, but you will have to re-start jsbuild when you add requires or new files.

Broken pipe errors

You will most likely get a lot of broken pipe errors. This does not seem to cause any problems with the build.