View source for Developer Area/Coding guidelines/JS files

This page documents the coding conventions used by Mahara for JavaScript files. Everything that ends up in the git repository (other than third-party code) should follow these standards.

You can also have a look at the [[Developer_Area/How_to_Review_Code|Reviewer's manual]] to see what reviewers will look at when looking at code submissions.

For other languages, use the links at the [[Developer_Area/Coding_guidelines|main guideline page]].

These guidelines are based on [http://javascript.crockford.com/code.html Crockford's code conventions].


=The Basics=

All files must adhere to the [[BasicJSFileTemplates]].

Indentation is using four (4) spaces. There is no requirement that the scripts are wrapped at 80 columns, however developers are asked to wrap long lines sensibly.

=Comments=

Comments of up to three lines in length should use the // comment marker. Comments longer than three lines should use /* ... */. Here is an example comment:

<div class="plugin tightenable"><code><font color="#000000"> <font color="#ff8000">/*<br />    This part is difficult, and requires a long<br />    explanation. This is that explanation. I am<br />    still typing to see if I can make it to four<br />    lines.<br /> */<br /></font> </font> </code></div>

Please note that the opening and ending markers are on their own lines - nothing else should be on these lines.


=Language Constructs=


==Strings==

Strings should be quoted with single quotes (') unless you are interpolating a variable.


==if/while/for statements==

There is one space after each language construct, and no spaces between brackets and the arguments inside them, '''unless''' what is inside them becomes too long for one line, in which case a special format will be used.

Examples of what is '''good''':

<div class="plugin tightenable"><code><font color="#000000"> <font color="#007700">if (</font><font color="#0000bb">1 </font><font color="#007700">== </font><font color="#0000bb">2</font><font color="#007700">) {<br />     return </font><font color="#dd0000">'omg'</font><font color="#007700">;<br /> }<br /><br /> while (</font><font color="#0000bb">i </font><font color="#007700">&lt; </font><font color="#0000bb">3</font><font color="#007700">) {<br />     return </font><font color="#dd0000">'I am ' </font><font color="#007700">+ </font><font color="#0000bb">i</font><font color="#007700">;<br /> }<br /><br /> for (</font><font color="#0000bb">i </font><font color="#007700">= </font><font color="#0000bb">0</font><font color="#007700">, </font><font color="#0000bb">j </font><font color="#007700">= </font><font color="#0000bb">7</font><font color="#007700">; </font><font color="#0000bb">i </font><font color="#007700">&lt; </font><font color="#0000bb">34</font><font color="#007700">, </font><font color="#0000bb">j </font><font color="#007700">!= </font><font color="#0000bb">3</font><font color="#007700">; </font><font color="#0000bb">i</font><font color="#007700">++, </font><font color="#0000bb">j</font><font color="#007700">--) {<br />     return (</font><font color="#0000bb">i </font><font color="#007700">* </font><font color="#0000bb">j</font><font color="#007700">) + </font><font color="#dd0000">' is a silly number'</font><font color="#007700">;<br /> }<br /><br /></font><font color="#ff8000">// Note bracing style of else if/else clauses<br /> // Also note: do not use elseif<br /></font><font color="#007700">if (</font><font color="#0000bb">a </font><font color="#007700">== </font><font color="#0000bb">b</font><font color="#007700">) {<br />     return </font><font color="#dd0000">"a = b"</font><font color="#007700">;<br /> }<br /> else if (</font><font color="#0000bb">c </font><font color="#007700">== </font><font color="#0000bb">d</font><font color="#007700">) {<br />     return </font><font color="#dd0000">"c = d"</font><font color="#007700">;<br /> }<br /> else {<br />     return </font><font color="#dd0000">"e = ?"</font><font color="#007700">;<br /> }<br /><br /></font><font color="#ff8000">// Ternary operator<br /></font><font color="#0000bb">a </font><font color="#007700">= (</font><font color="#0000bb">b </font><font color="#007700">== </font><font color="#0000bb">true</font><font color="#007700">) ? </font><font color="#dd0000">'hello' </font><font color="#007700">: </font><font color="#dd0000">'goodbye'</font><font color="#007700">;<br /></font><font color="#ff8000">// When used with other things on each side in the same statement:<br /></font><font color="#0000bb">a </font><font color="#007700">= </font><font color="#dd0000">'foo' </font><font color="#007700">+ ((</font><font color="#0000bb">b </font><font color="#007700">== </font><font color="#0000bb">true</font><font color="#007700">) ? </font><font color="#dd0000">'hello' </font><font color="#007700">: </font><font color="#dd0000">'goodbye'</font><font color="#007700">) + </font><font color="#dd0000">'bar'</font><font color="#007700">;<br /><br /></font><font color="#ff8000">// A complicated condition. Note location of condition,<br /> // and location of ending bracket and brace.<br /> // todo: what was the decision here regarding conditions on the "if (" line?<br /></font><font color="#007700">if (<br />     </font><font color="#0000bb">sacrificedgoats </font><font color="#007700">== </font><font color="#0000bb">availablegoats<br />     </font><font color="#007700">&amp;&amp; (</font><font color="#0000bb">dogs </font><font color="#007700">== </font><font color="#0000bb">cats<br />     </font><font color="#007700">|| </font><font color="#0000bb">1 </font><font color="#007700">!= </font><font color="#0000bb">2</font><font color="#007700">)<br />     || (</font><font color="#0000bb">yesterday </font><font color="#007700">&gt;&gt; </font><font color="#0000bb">tomorrow </font><font color="#007700">== </font><font color="#0000bb">4</font><font color="#007700">)<br /> ) {<br />     </font><font color="#ff8000">// Do stuff<br /></font><font color="#007700">}<br /></font> </font> </code></div>

Examples of what is '''bad''':

<div class="plugin tightenable"><code><font color="#000000"> <font color="#007700">if ( </font><font color="#0000bb">a </font><font color="#007700">== </font><font color="#0000bb">b </font><font color="#007700">)<br /> {<br />     return </font><font color="#dd0000">'hi'</font><font color="#007700">;<br /> }<br /><br /> if(</font><font color="#0000bb">c </font><font color="#007700">== </font><font color="#0000bb">d</font><font color="#007700">) {<br />     return </font><font color="#dd0000">'hi'</font><font color="#007700">;<br /> } else {<br />     return </font><font color="#dd0000">'bye'</font><font color="#007700">;<br /> }<br /><br /> if (</font><font color="#0000bb">e</font><font color="#007700">==</font><font color="#0000bb">f</font><font color="#007700">)<br /> {<br />     return </font><font color="#dd0000">'hi'</font><font color="#007700">;<br /> }<br /> else<br /> {<br />     return </font><font color="#dd0000">'bye'</font><font color="#007700">;<br /> }<br /></font> </font> </code></div>

What should be '''never''' used:

<div class="plugin tightenable"><code><font color="#000000"> <font color="#ff8000">// For a really short condition<br /></font><font color="#007700">if (</font><font color="#0000bb">a </font><font color="#007700">== </font><font color="#0000bb">b</font><font color="#007700">) </font><font color="#0000bb">c </font><font color="#007700">= </font><font color="#0000bb">1</font><font color="#007700">;<br /><br /></font><font color="#ff8000">// Just don't. Not even ow.<br /></font><font color="#007700">do {<br />     echo </font><font color="#dd0000">'hi'</font><font color="#007700">;<br /> } while (</font><font color="#0000bb">a </font><font color="#007700">== </font><font color="#0000bb">1</font><font color="#007700">);<br /></font> </font> </code></div><div id="section_7">

==Variables and Arrays==

Variables should be named with no underscores, and no capital letters. This policy may become more lenient in future if variable names are discovered that are not easily readable without underscores.

Do not name variables as negatives where possible - always use positive names and logical inversion (!) where required.

Hungarian notation is forbidden.

When related variables are initialised, the = signs for them should line up. Other than that, aligning = signs for variable assignment is up to the developer, although they should use common sense in such decisions.

Good:

<div class="plugin tightenable"><code><font color="#000000"> <font color="#0000bb">var found </font><font color="#007700">= </font><font color="#0000bb">false</font><font color="#007700">;<br /></font><font color="#0000bb">var ponies </font><font color="#007700">= </font><font color="#0000bb">0</font><font color="#007700">;<br /></font><font color="#0000bb">var servername </font><font color="#007700">= </font><font color="#0000bb">var overkill</font><font color="#007700">;<br /><br /></font><font color="#ff8000">// Only in relation to controlling for/while loops<br /></font><font color="#007700">for (var </font><font color="#0000bb">i </font><font color="#007700">= </font><font color="#0000bb">10</font><font color="#007700">; </font><font color="#0000bb">i </font><font color="#007700">&gt; </font><font color="#0000bb">5</font><font color="#007700">; </font><font color="#0000bb">i</font><font color="#007700">--) {<br />     tmp += </font><font color="#0000bb">i</font><font color="#007700">;<br /> }<br /><br /></font><font color="#ff8000">// Aligning = signs<br /></font><font color="#0000bb">var mine   </font><font color="#007700">= </font><font color="#0000bb">0</font><font color="#007700">;<br /></font><font color="#0000bb">var yours  </font><font color="#007700">= </font><font color="#0000bb">0</font><font color="#007700">;<br /></font><font color="#0000bb">var theirs </font><font color="#007700">= </font><font color="#0000bb">0</font><font color="#007700">;<br /><br /></font><font color="#ff8000">// Only if the number of elements to initialise is small.<br /></font><font color="#0000bb">var object </font><font color="#007700">= [</font><font color="#0000bb">1 </font><font color="#007700">=&gt; </font><font color="#dd0000">'hello'</font><font color="#007700">];<br /><br /></font><font color="#ff8000">// If large number of elements to initialise:<br /></font><font color="#0000bb">var array </font><font color="#007700">= {<br />     </font><font color="#0000bb">1  </font><font color="#007700">: </font><font color="#dd0000">'hello'</font><font color="#007700">,<br />     </font><font color="#0000bb">2  </font><font color="#007700">: </font><font color="#dd0000">'goodbye'</font><font color="#007700">,<br />     </font><font color="#0000bb">10 </font><font color="#007700">: </font><font color="#dd0000">'erm'<br /></font><font color="#007700">};<br /></font> </font> </code></div>

TODO: mention actual arrays, we have only done objects

Bad:

<div class="plugin tightenable"><code><font color="#000000"> <font color="#ff8000">// Negative name<br /></font><font color="#0000bb">notfound </font><font color="#007700">= </font><font color="#0000bb">true</font><font color="#007700">;<br /></font><font color="#ff8000">// Underscores<br /></font><font color="#0000bb">var my_variable </font><font color="#007700">= </font><font color="#dd0000"><nowiki>''</nowiki></font><font color="#007700">;<br /></font><font color="#ff8000">// Hungarian. Eew....<br /></font><font color="#0000bb">var count_i </font><font color="#007700">= </font><font color="#0000bb">6</font><font color="#007700">;<br /></font><font color="#ff8000">// Uppercase letters<br /></font><font color="#0000bb">var myFish </font><font color="#007700">= </font><font color="#0000bb">var yourFish</font><font color="#007700">;<br /><br /></font><font color="#ff8000">// Not necessarily "bad", just not for this project<br /></font><font color="#0000bb">var object </font><font color="#007700">= {<br />                 </font><font color="#0000bb">1 </font><font color="#007700">: </font><font color="#dd0000">'hello'</font><font color="#007700">,<br />                 </font><font color="#0000bb">2 </font><font color="#007700">: </font><font color="#dd0000">'goodbye'</font><font color="#007700">,<br />                 </font><font color="#0000bb">10 </font><font color="#007700">: </font><font color="#dd0000">'erm'<br />               </font><font color="#007700">};<br /></font> </font> </code></div></div><div id="section_8">

==Binary Operators==

Always have a space on each side:

<div class="plugin tightenable"><code><font color="#000000"> <font color="#007700">echo </font><font color="#0000bb">1 </font><font color="#007700">+ </font><font color="#0000bb">2</font><font color="#007700">;<br /> if (</font><font color="#0000bb">1 </font><font color="#007700">== </font><font color="#0000bb">2</font><font color="#007700">)<br /> echo </font><font color="#dd0000">'hello' </font><font color="#007700">. </font><font color="#dd0000">' world'</font><font color="#007700">;<br /></font> </font> </code></div>

<nowiki>|| and &amp;&amp; will always be used for 'or' and 'and' respectively. Resolve priority collisions with extra brackets as required.</nowiki>

==Functions and Methods==

'''Declaration:'''

<div class="plugin tightenable"><code><font color="#000000"> <font color="#ff8000">/**<br /> * PHPDoc comment describing the function<br /> *<br /> * Note how the default value has no spaces<br /> */<br /></font><font color="#007700">function </font><font color="#0000bb">foo</font><font color="#007700">(</font><font color="#0000bb">$a</font><font color="#007700">, Class </font><font color="#0000bb">$b</font><font color="#007700">, </font><font color="#0000bb">$c</font><font color="#007700">=</font><font color="#dd0000"><nowiki>''</nowiki></font><font color="#007700">) {<br />     </font><font color="#ff8000">// source<br />     </font><font color="#007700">return </font><font color="#0000bb">$value</font><font color="#007700">;<br /> }<br /><br /> class </font><font color="#0000bb">FooBar </font><font color="#007700">extends </font><font color="#0000bb">Bar </font><font color="#007700">{<br /><br />     </font><font color="#ff8000">/**<br />      * PHPDoc for the field<br />      *<br />      * For this project, do not use doThis.<br />      */<br />     </font><font color="#0000bb">public </font><font color="#007700">function </font><font color="#0000bb">do_this</font><font color="#007700">(</font><font color="#0000bb">$c</font><font color="#007700">, </font><font color="#0000bb">$d</font><font color="#007700">) {<br />         </font><font color="#ff8000">// source<br />     </font><font color="#007700">}<br /><br /> }<br /></font> </font> </code></div>

'''Calling:'''

<div class="plugin tightenable"><code><font color="#000000"> <font color="#0000bb">$result </font><font color="#007700">= </font><font color="#0000bb">foo</font><font color="#007700">(</font><font color="#0000bb">$bar</font><font color="#007700">, </font><font color="#0000bb">$baz</font><font color="#007700">);<br /></font><font color="#0000bb">$mine </font><font color="#007700">= </font><font color="#0000bb">$object</font><font color="#007700">-&gt;</font><font color="#0000bb">method</font><font color="#007700">(</font><font color="#0000bb">$a</font><font color="#007700">, </font><font color="#0000bb">$b</font><font color="#007700">);<br /><br /></font></font></code></div></div>

=Javascript=
All files must adhere to the [[BasicJSFileTemplates]].
Javascript files should roughly follow [http://javascript.crockford.com/code.html Crockford's code conventions].