Southend Linux User Group

Javascript Guidelines

JavaScript coding guidelines

By establishing a few coding guidelines your code can becomes more readable and easier to edit. The following should be
considered as guidelines, rather than standards. The guidelines an be broken down as follows.

  • Naming conventions
  • Syntax
  • Spacing, indenting and Braces
  • Comments
  • Parentheses
  • Documentation

Naming conventions

A variable naming convention is one of the main factors in determining the readability of the code. Is it easier to figure out the purpose of a variable named postcode or p? Single character variable names convey little or no meaning. If they are used they are usually confined to variables used for repetition (looping).

CamelBack notation

How you name functions and variables is up to you, but for reasons of clarity, names should be indicative of their purpose, There are three naming conventions that are traditionally used. The first is based on the camelBack notation. (Optionally) start with a lowercase letter, and then the first letter of each subsequent word should be uppercase, with all other letters lowercase. e.g. firstName.
An alternative to camelBack notation is to use underscores to separate words. e.g. first_Name. Whichever naming convention you chose to adopt, stick to it.

One thing you cannot do, is leave spaces between the words that form a variables name. This will almost certainly result in a syntax error. The program may run up to the point where it detects a syntax error, or worse, just not run at all.

Javascript is case sensitivee.g. the variables area and Area are two different variables.

Javascript syntax

Just as any plain language, such as English, has its own grammar, programming languages have their own grammar (or syntax). Unlike plain language however, where a missing comma, or full stop, probably doesn’t alter the meaning of a sentence, the syntax of a program language must be rigorously adherred to.

A programming language will have a list of reserved words. These can only be used in the context defined by the syntax of the language. Reserved words must not be used for variable names etc. Spaces (along with tabs and newlines used outside of string constants, are referred to as white space), should be used to improve readability, but they do not form part of the syntax. In the example below the keywords, including semi colons, curly brackets etc. are highlighted in blue.

  var myVariable = function myFunctionName (arg1,arg2 ...)
  {
      // a comment
       var myLocalVariable = arg1 * arg2 ;
       return myLocalVariable ; 
  } 

(Automatic) semicolon insertion – a statement that is considered well formed when a newline is parsed by the browser will be considered complete. I.e. the browser will (automatically) insert a semicolon just prior to the newline. You must therefore take care when breaking a long line of code, and should include semicolons explicitly,

A pair of curly brackets { } and an enclosed sequence of statements constitute a block (or compound) statement, which can be used wherever a statement can be used.

Spacing and indenting and braces

White space, along with indenting, should be used to improve readability. Indenting nested statements is also an aid to readability. Javascript utilizes curly braces to denote blocks of code such as functions.. Some programmers prefer to put the first brace on the same line as the function declaration, others place it on a separate line. E.g.

 for ( var x=1; x<10; x++ ) {
    ... some code
    for ( var y=1; y<10; y++ ) {
       ... more code
 }

Alternatively

 for ( var x=1; x<10; x++ )
 {
    ... some code
    for ( var y=1; y<10; y++ )
    {
       ... more code
    }
 }

It is recommended you adopt the second option, as this allows braces to be lined up within the code, making it easier when debugging missing braces.

What do the three dots mean?. There are the symbol for an ellipsis, not to be confused with an ellipse. The three dots (maybe more if I get carried away) mean an omission, usually for the sake of clarity. Adding the missing content would not add anything to what is trying to be conveyed. They are not part of the Javascript language.

Comments

Properly commenting code as it is developed is important for reasons of maintainability. It is better to have to many rather than to few comments. They may be stripped out of production (working) versions. Also for maintenance reasons at the start of your comments should be some indication of its version. This may be just a date, or a number indicating Major.Minor revisions.

  • All variables should include a short comment describing their purpose.
  • All custom functions and objects should contain a comment sections at the start.

Parentheses

Use parentheses to ensure calculated values are as expected. It is often easier to insert parentheses, than recall the operator precedence.

Debugging your scripts

Unfortunately is your script contains errors, usually it just doesn’t run at all. The vast majority of errors are syntax errors including typing errors. An essential skill for any programmer is to read what you have written, not what you think you have written. The second kind of error are logical errors. Essentially the program has done exactly what you asked it to do, however this is not what you intended.

Documentation

For most (small/medium) projects additional documentation is usually unnecessary, provided the code has been properly commented in the first place. However for more complex projects, especially when error detection and correction code is added , obscuring the core functionality, documentation will help with the initial introduction of any new program. Such documentation may be incorporated into the code as on-line contextual help for example.

There are often instances where the underlying concept behind the code needs to be explained, as anyone who is unfamiliar with the idea, may find the code particularly impenetrable. For example if you are not familiar with the concept of a binary tree, you may find a recursive sort program base on this, particularly hard to follow.

Similarly, mathematical constructs, like complex numbers may need some further explanation, when converting between polar and rectangular coordinate systems for example.

Obscuration is not good programming practice, especially if you also subscribe to the notions of open source.

Author: Alan Campion - Page reference: 568
Last modified: Alan Campion - 2015-01-22