Difference between revisions of "Developer Area/Coding guidelines/JS files"

From Mahara Wiki
Jump to navigation Jump to search
(Created page with "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 st…")
 
Line 30: Line 30:
 
Strings should be quoted with single quotes (') unless you are interpolating a variable.
 
Strings should be quoted with single quotes (') unless you are interpolating a variable.
  
 
==require/require_once/include/include_once==
 
 
These statements should have brackets around the argument. There is no space between the statement and the bracket. In effect, this is the same as a function call.
 
 
<div class="plugin tightenable"><code><font color="#000000"> <font color="#007700">require_once(</font><font color="#dd0000">'my/file.php'</font><font color="#007700">);<br /></font> </font> </code></div>
 
 
'''NOT''':
 
 
<div class="plugin tightenable"><code><font color="#000000"> <font color="#007700">require_once </font><font color="#dd0000">'my/file.php'</font><font color="#007700">;<br /> require_once (</font><font color="#dd0000">'my/file.php'</font><font color="#007700">);<br /></font> </font> </code></div>
 
 
Plugin files '''must''' be included using the [http://mahara.eduforge.org/api/mahara/core/_lib---mahara.php.html#functionsafe_require <span style="white-space: nowrap">[[Image:http.png]]safe_require</span>] function. This function ensures that there are no vulnerabilities in accessing a plugin file. Plugins that do not use this function to include files should be considered vulnerable to a possible security vulnerability.
 
 
Any include statements in the core should '''never''' have a variable in their name, to reduce the chance of an arbitary include vulnerability.
 
 
The include path is set automatically to be the current directory plus the lib directory - there is no need to specify an absolute directory path.
 
  
 
==if/while/for statements==
 
==if/while/for statements==
Line 53: Line 37:
 
Examples of what is '''good''':
 
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 />     die(</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 />     echo </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 />     echo (</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 />     echo </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 />     echo </font><font color="#dd0000">"c = d"</font><font color="#007700">;<br /> }<br /> else {<br />     echo </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>
+
<div class="plugin tightenable"><code><font color="#000000"> <font color="#007700">if (</font><font color="#0000bb">condition</font><font color="#007700">) {<br />     statement<br /> }<br /><br /> while (</font><font color="#0000bb">expressionn </font>) {<br />     statement<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 />     statement<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">expression</font><font color="#007700">) {<br />     statement<br /> }<br /> else if (</font><font color="#0000bb">condition2<font color="#007700">) {<br />     statement2<br /> }<br /> else {<br />     statement3<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''':
 
Examples of what is '''bad''':

Revision as of 23:45, 29 August 2012

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 Reviewer's manual to see what reviewers will look at when looking at code submissions.

For other languages, use the links at the main guideline page.

These guidelines are based on 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:

/*
   This part is difficult, and requires a long
   explanation. This is that explanation. I am
   still typing to see if I can make it to four
   lines.
*/

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:

if (condition) {
    statement
}

while (
expressionn ) {
    statement
}

for (
i = 0, j = 7; i < 34, j != 3; i++, j--) {
    statement
}

// Note bracing style of else if/else clauses
// Also note: do not use elseif
if (expression) {
    statement
}
else if (
condition2) {
    statement2
}
else {
    statement3
}

// Ternary operator
a = (b == true) ? 'hello' : 'goodbye';
// When used with other things on each side in the same statement:
a = 'foo' . ((b == true) ? 'hello' : 'goodbye') . 'bar';

// A complicated condition. Note location of condition,
// and location of ending bracket and brace.
// todo: what was the decision here regarding conditions on the "if (" line?
if (
    
sacrificedgoats == availablegoats
    
&& (dogs == cats
    
|| 1 != 2)
    || (
yesterday >> tomorrow == 4)
) {
    
// Do stuff
}

Examples of what is bad:

if ( $a == $b )
{
    echo
'hi';
}

if(
$c == $d) {
    echo
'hi';
} else {
    echo
'bye';
}

if (
$e==$f)
{
    echo
'hi';
}
else
{
    echo
'bye';
}

What should be never used:

// For a really short condition
if ($a == $b) $c = 1;

// Just don't. Not even ow.
do {
    echo
'hi';
} while (
$a == 1);

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:

$found = false;
$ponies = 0;
$servername = $overkill;

// Only in relation to controlling for/while loops
for ($i = 10; $i > 5; $i--) {
    echo
$i;
}

// Aligning = signs
$mine   = 0;
$yours  = 0;
$theirs = 0;

// Only if the number of elements to initialise is small.
$array = array(1 => 'hello');

// If large number of elements to initialise:
$array = array(
    
1  => 'hello',
    
2  => 'goodbye',
    
10 => 'erm'
);

Bad:

// Negative name
$notfound = true;
// Underscores
$my_variable = '';
// Hungarian. Eew....
$count_i = 6;
// Uppercase letters
$myFish = $yourFish;

// Not necessarily "bad", just not for this project
$array = array(
                
1 => 'hello',
                
2 => 'goodbye',
                
10 => 'erm'
              
);

Binary Operators

Always have a space on each side:

echo 1 + 2;
if (
1 == 2)
echo
'hello' . ' world';

|| and && will always be used for 'or' and 'and' respectively. Resolve priority collisions with extra brackets as required.

Functions and Methods

Declaration:

/**
* PHPDoc comment describing the function
*
* Note how the default value has no spaces
*/
function foo($a, Class $b, $c='') {
    
// source
    
return $value;
}

class
FooBar extends Bar {

    
/**
     * PHPDoc for the field
     *
     * For this project, do not use doThis.
     */
    
public function do_this($c, $d) {
        
// source
    
}

}

Calling:

$result = foo($bar, $baz);
$mine = $object->method($a, $b);

Javascript

All files must adhere to the BasicJSFileTemplates. Javascript files should roughly follow Crockford's code conventions.