Version 8 (modified by fhuici, 8 years ago)

--

Provisional HEN JavaScript? coding style

This is a *provisional* attempt to lay down some rules that we can adhere to and moan about. The style is only intended to apply to new code, not code that we import. Hopefully, the style is equidistant from our default coding styles that all are equally peturbed.

DOCTRINE

Ignore any section of this document when doing so would enhance readability. Feel free to edit someone else's code into agreement with these principles, or into agreement with your own variant of these principles. Expect that your code may be likewise edited.

FILE PROLOGUES

Files should have a prologue containing the copyright, a description of what the file does and which classes it implements, if any.

INDENTATION

Use 2 spaces per indent level. This is what emacs' JavaScript? mode does.

BRACES

Place braces on separate lines unless the braces contain a small single statement (make sure that the braces are on the same column as the statement they belong to). E.g., prefer:

        if (abc == 3)
        {
                /* XXX */
        }

to:

        if (abc == 3) {
                /* XXX */
        }

exception:

        if (abc == 3) { abc++; }

For the sake of readability, try to place white space either side of braces. E.g., prefer:

        function foo() { return _some_value; }

to:

        function foo() {return some_value;}

SEMICOLONS

While JavaScript? does not require this, their absence confuses emacs' indentation, so do use them.

COMMENTS

Use // for comments.

Avoid obvious comments inside routines. Any comments inside routines should be short, when possible. Prefer blank lines for separating sections of code.

API DOCUMENTATION (jsdoc)

All major routines should have a comment briefly describing what they do. We use jsodc comments (similar to javadoc) to generate API overviews and programming documentation.

TERMINAL WIDTH

Assume the terminal is 80 characters wide. Sure there'll be odd times when wraps cannot be avoided, but gratuitous wrapping will give you a "wide boy" reputation.

CAPITALIZATION

        auxiliary.hen.SensorNode = function()
        {
          this.sensorNodeId = null;
          
          this.setSensorNodeId = function setSensorNodeId(id)
          {
            this.sensorNodeId = id;
          };
        }

Use all caps for constants, global or otherwise, using underscores to separate the different words in the constant's name.

NAMES FOR MODIFIERS AND ACCESSORS

In general we haven't really bothered to right modifiers and accessors, but for those who wished to do so if the variable is named "xxx", name the getter function "getXxx()" and the setter function "setXxx()".

ABBREVIATIONS

Should be avoided, especially in method names.

- SPACES AND PARENTHESES

Binary operators should have spaces around them to ease decipherment. Parentheses have to used when precedence dictates and can be used to reduce confusion, particularly with long expressions. Do not put spaces around parentheses.

Keywords should likewise have spaces around them. For example, if (x)', not if(x)'; and return x', not return(x)'.

VARIABLE DECLARATIONS

Although JavaScript? allows to declare a variable without 'var', do use this keyword when declaring them. Place variable declarations at the beginning of the relevant scope. This includes placing declarations in the middle of functions, close to their first uses, when appropriate. Declare iteration variables inside the `for' statement when possible; this is most of the time. Declare a test variable inside the `if' test when possible; this happens comparatively rarely. Prefer multiple declarations when defining several variables that require initializers.

GLOBAL VARIABLES

These are to be avoided whenever possible. Instead, try to place things in classes. If programming a tab for the GUI, append the name of the global with the name of the tab. For instance, for a variable named color in the experiment tab, use experimentTabColor.