Javascript/Coding Style

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

The Moodle JavaScript coding style

Overview

Although most of the Moodle standard coding style applies to JavaScript, there are a number of exceptions. These are largely as a result of common practice within the JavaScript community, or for increased clarity given different terminology when dealing with frontend code (e.g. use of cartesian positions).

Scope

This document describes style guidelines for developers work on or with JavaScript code in Moodle.

Goals

Consistent coding style is important in any development project, and particularly when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Abstract goals we strive for:

• simplicity
• readability
• tool friendliness

Naming conventions

Variable and function naming

Contrary to the standard Moodle coding style, we prefer to use camelCase for JavaScript.

The justification for this is that:

• it is a commonly accepted practice within the wider JavaScript community;
• it is easier to read when dealing with variables describing cartesian points (e.g. currenty versus currentY); and
• it is the style used by the upstream YUI library for all variable names, and all CSS settings.

Correct

   var currentY,
   courseCategory,
   lastValue,
   lastBackgroundColor;

Incorrect

var current_y,

   currenty,
   course_category,
   coursecategory,
   last_value,
   lastvalue,
   last_background_color,
   lastbackgroundcolor;

Variable declaration

As usual with JavaScript, all variables musut be declared once for the scope in which they are used using the ```var``` keyword.

Number of variable declarations

The number of variable declarations should be kept to a sensible minimum.

Correct

var oneVariable,

   twoVariable,
   threeVariable,
   more;

// Some other code goes here which breaks up the logical flow

// Some more variable definitions relating to the next set of code goes // here. var anotherVariable,

   andAnother;

Incorrect

var oneVariable; var twoVariable; var threeVariable; var more;

Initial values

Variable definitions describing variables which have initial content should:

• fit on a single line in the case of simple types;
• be spread across multiple lines for complex types (including 'all' objects and arrays, no matter how simple); and
• empty object and array definitions should break into multiple lines. This is so that should values be added later the history on the surrounding lines is preserved.

Correct

   var aBoolean = true,
   aNumber = 10,
   anObjectWithoutContent = {
   },
   anObjectWithContent = {
       exampleContent: 'value'
   };

Incorrect

   var oneVariable;
   var twoVariable;
   var threeVariable;
   var more;

Whitespace

TODO: Spacing between variable names and values:

   var flatValue = 'value',
   anObject = {
       someKey: 'someContent'
   };

Documentation and comments

We are attempting to document all YUI modules that we write and as such largely follow the upstream YUI guidance which is available at http://yui.github.io/yuidoc/syntax/index.html.

General notes

• Unless otherwise specified, comments should conform to the general style guidelines;
• all comments must start with leading whitespace before the first word on each line; and
• all indentation must be in addition to any existing leading whitespace on the line.

Official documentation

All JavaScript documentation must:

• use the correct docblock format;
• use the correct JavaScript types where relevant (note, Int is not a valid type in JavaScript);
• use all appropriate tags;
• produce valid documentation using the YUIDoc toolset;
• have a linebreak between the description and the list of tags.

Note:

YUIDoc will only generate documentation for docblocks starting with /**.

YUIDoc will try to generate documentation for *all* docblocks starting /**.

Correct

/**

* This is an example docblock comment. It describes a function called
* marmite.
*
* It adds a number of jars of marmite to the cupboard.
*
* @method addMarmite
* @param {Number} [jarCount=1] The number of jars of marmite to add to the
* cupboard. This parameter is optional and defaults to 1.
* @chainable
*/

Incorrect

/*

* This is an invalid comment block. It wouldn't be picked up by yuidoc as
* the comment style is incorrect.
*
* @method foo
*/

// This is also an invalid comment block and wouldn't be picked up by // YUIDoc.

/**

• Although this style would be picked up by YUIDoc, it is hard to read.
• @method foo
• /

/**

*Although this style would be picked up by YUIDoc, it is also hard to read.
*
*@method foo
*/

/**

* This docblock is mostly valid but does not include a linebreak between
* the description, and the tags.
* @method foo
*/

General comments

All shorter comments, for example those explaining the subsequent few lines of code should use the // style of comments.

Comments not intended for official documentation must *not* use the Docblock style of commenting as YUIDoc will attempt to include the comment in official documentation.

Correct

// This is a valid set of comments for one line.

// And this is a valid longer comment to describe the subsequent few lines // in as much detail as required. It can consist of multiple sentences, as // long as each new line starts with the correct comment style.

Incorrect

/* This is an invalid comment style for short comments. */

//This is also an invalid style as there is no leading whitespace after the //comment indicator.

/**

* This is an invalid multi-line comment. Multi-line comments should not
* use the docblock style comments unless they are a valid and fully
* formatted docblock.
*/

/*

* This is an also invalid multi-line comment. Although it is not a full
* docblock style, it does not start with the // style of comment
* indicator.
*/