Quality Management:Quality manual/Work instructions/JavaScript coding standard

This document is not released - Draft version only

This coding standard is used for all JavaScript programming. That is, but not limited to, JavaScript and extensions to Dojo, YUI, jQuery and Prototype.

The scope of this document is to define coding standards related to the JavaScript language. Review and quality control is not covered herein. Please refer to Peer review.

JavaScript

This document is under preparation, the following areas should be covered:

• PHP test page
• sourcefile/production file
• naming..
• Peer review check list

Peer review

When performing peer code review the following guidelines shall be followed:

• Guidelines specified in Best Practices Java Script
• Guidelines specified below

Validation

All released java scripts must be validated by JSLint.com or similar tools, However, the following exceptions are allowed: • It is not recommended to use the “ (??) Any exception shall be explained in the comments to the actual code line.

Furthermore, the script shall be run in Firefox and verified in the error console Firebug.

File header

All source files must contain a file header with informations specified by the procedure for Control of Documents. An practical example may be found below:#Document History. Text to copy into the source file may be found here: Source Code file header.

Function names

All functions names starts with low-case.

Constructor

The variable name of variable containing a function reference must start upper-case.

<script type="text/javascript">
var Person = function(name){
                this.name = name;
             }
var eljefe = new Person ('Peter Stig Andersen');
print(eljefe.name);
</script>

This is to avoid programming errors where the lack of "new" would lead to use/modification of the global context.

Variable declaration

All variables must be declared prior to use.

<script type="text/javascript">
// a globally-scoped variable
var a=1;

// global scope
function one(){
  a = 2;  
  alert(a); 
}
</script>

and

<script type="text/javascript">
// a globally-scoped variable
var a=1;

// local scope
function one(){
   var a = 2; 
   alert(a); 
}
</script>

Provides different functions!

Don't use HTML comment within javascript

To day all browsers are able to handle the <script> tag, therefore there is no need for the construction used (before year 2000) to handle java script incompatible browsers. Furthermore, today some browsers eg. IE will hide java script enclosed by the HTML comments!

Therefore, never use this construction:

<script type="text/javascript">
<!--
   // code here
//-->
</script>

Dojo - Dijit - Javascript

• Read more about Dojo and Declarative HTML5

• Debugging: A very good page on Javas cript debugging: sitepen javascript debugging techniques

HTML5 dijits

When defining HTML5 dijits (Declarative) the following applies:

Both single and double quotes are allowed in the HTML5 specification. However, when declaring HTML5 Dijits it is preferable only to use double quotes in the HTML5 part and single quotes in the Dijit declaration part like this:

    <button data-dojo-type="dijit.form.Button" id="b2"
            data-dojo-props="onClick: function (){ dojo.byId('result1').innerHTML += 'You clicked the Declared button!<br>';}  ,
                              type: 'button' ">
    dijit.form.Button declared in HTML!
    </button>
    <div data-dojo-type="dijit.Tooltip" 
         data-dojo-props=" connectId: ['b2'],
                           position:  ['below']">
    Please click me.. I am <i>Declared in HTML</i>. The possition is <b>below</b> the button.
    </div>    
    </p><p>    
    <div id="result1"></div>
    </p>

See the demo of the above code: dijit.form.Button and dijit.Tooltip

Furthermore, all texts inserted from eg. a Database query must be escaped according to the Java Script standard (\" and \') and according to the HTML standard (& q u o t ; and & # 0 3 9 ;).

This can be done with a PHP function like this:

function dijitTextInsert ($string){
   return htmlspecialchars( addslashes( $string, ENT_QUOTES) );
}

Further informations: Double and single quotes in HTML5 dijits

References

To be reviewed:

• add description
• [1]

References:

• Best Practices Java Script
• vs.dojo vs.yui (Performance)
• See all references here: References.

Document History

Version	Date	Author	Status	Purpose of update
1	23 Apr 2011	PSA	Draft	New document
2	25 Okt 2011	PSA	Draft	Don't use HTML comments.. added.
3	06 Nov 2011	PSA	Draft	HTML5 Dijits, use of quotes added.
4	13 Dec 2011	PSA	Draft	References corrected