View source for 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 [[CL:Quality_Management/Peer_review|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 [http://www.javascripttoolbox.com/bestpractices/ 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 [[Dojo Dijit and HTML5 in Real world applications/Firebug|Firebug]].

===File header===
All source files must contain a file header with informations specified by the procedure for [[QM:Quality_manual/Procedures/Control_of_documents|Control of Documents]]. An practical example may be found below:[[#Document History]]. Text to copy into the source file may be found here: [[QM:Templates/Source Code file header|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.

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

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.
<syntaxhighlight lang="JavaScript">
<script type="text/javascript">
// a globally-scoped variable
var a=1;

// global scope
function one(){
  a = 2;  
  alert(a); 
}
</script>
</syntaxhighlight>
and 
<syntaxhighlight lang="JavaScript">
<script type="text/javascript">
// a globally-scoped variable
var a=1;

// local scope
function one(){
   var a = 2; 
   alert(a); 
}
</script>
</syntaxhighlight>
Provides different functions!
===Don't use HTML comment within javascript===
To day all browsers are able to handle the &lt;script&gt; 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:
<syntaxhighlight lang="JavaScript">
<script type="text/javascript">
<!--
   // code here
//-->
</script>
</syntaxhighlight>

==Dojo - Dijit - Javascript==
* Read more about [[CL:Web/Dojo_HTML5_vs_HTML4_Declarative_vs_Programmatic|Dojo and Declarative HTML5]]

* Debugging: A very good page on Javas cript debugging: [http://www.sitepen.com/blog/2008/04/03/advanced-javascript-debugging-techniques/ 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:
<syntaxhighlight lang="html5">
    <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>
</syntaxhighlight>
See the demo of the above code: [http://pmis.biz/rwa/dijit.form.Button_1.php 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:
<syntaxhighlight lang="php">
function dijitTextInsert ($string){
   return htmlspecialchars( addslashes( $string, ENT_QUOTES) );
}
</syntaxhighlight>
Further informations: [[Dojo_Dijit_and_HTML5_in_Real_world_applications/Dijit/Double_and_single_quotes_in_HTML5_dijits|Double and single quotes in HTML5 dijits]]

==References==
To be reviewed:
* [http://c2.com/cgi/wiki?JavaScriptCodingStandard|C2.com add description]
* [http://drupal.org/node/260140]

References:
* [http://www.javascripttoolbox.com/bestpractices/ Best Practices Java Script]
* [http://tech.yes-co.nl/2009/08/25/jquery-versus-dojo-versus-yui/|jquery vs.dojo vs.yui (Performance)]
* See all references here: [[QM:Quality_manual#References|References]].

==Document History==
{| class="wikitable"
|-
! 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
|-
| 
| 
| 
| 
| 
|}
[[Category:software development]]