Coding guides

From Armarius

The following guidelines are meant to help us better understand each other's code and thus collaborate more efficiently. By respecting these, we can create an easy-to-maintain software, and also help others interested in the project to contribute. The rules set forth there are by no means exhaustive or ideologically correct. Please send comments, observation, suggestions about these guides to the mailing list.

Each guideline is followed by a rationale section explaining why the rule is necessary.

Contents 1 Source code formatting guides 1.1 Indentation 1.2 Naming conventions 1.3 Commens

[edit] Source code formatting guides

• Tabs and spaces are allowed. Tabs should be 4 spaces long.

Rationale: 8 characters long tabs push the text too much to the right, resulting in long lines.

• Very long lines (>120 characters) should be splited. When splitting indentation should be preserved. For instance:

this.container = createElement(document, {tagName:"iframe",src:this.cont_html_source, scrolling:"auto", frameBorder:0,className:this.cont_class});

should be splitted as:

this.container = createElement(document, {tagName:"iframe",  src:this.cont_html_source, 
                                         scrolling:"auto", frameBorder:0,className:this.cont_class});

Rationale: Long lines require scrolling to read and might not display properly on narrow terminals

• If a long line is split along operators(except for comma and semicolon), operators should be placed at the beginning of the new line.

Example:

 header('Set-Cookie: ' . rawurlencode($Name) . '=' . rawurlencode($Value)
                        . (empty($Expires) ?  : '; expires=' . gmdate('D, d-M-Y H:i:s', $Expires) . ' GMT')
                        . (empty($Path) ?  : '; path=' . $Path)
                        . (empty($Domain) ?  : '; domain=' . $Domain)
                        . (!$Secure ?  : '; secure')
                        . (!$HTTPOnly ?  : '; HttpOnly'), false);

Rationale: It is difficult to spot an operator that is placed at the end of the line, especially, in a block whose lines are of variable length

[edit] Indentation

• For PHP use the php-style indentation (place opening curly braces in a new line, at the same indentation level as the previous instruction):

if (condition)
{
    satement....
}

• For JavaScript, use K&R-style indentation:

if (condition) {
    "statement"
}

Rationale: This follows the suggested indentation style of both programming languages

[edit] Naming conventions

• All variable, function and constant names shall be in English.
• PHP variable and function should follow the GNU naming convention. A variable should be named as $var_name_name, with all lowe-case words separated by underscrolls. A name should not contain more the 4 words. Function names should follow the same convention. For class names, use a concatenated list of capitalized words as in SomeClassName. Constant names should use all uppercase, and begin with a prefix to avoid name collisions. Words in a constant name should be delimited by underscrolls. Example of a valid constant name: NOTE_TITLE

Rationale: Words separated by underscroll is easier to read than words in camel case (though they might be harder to write)

• JavaScript code should follow the Java naming convention for classes, methods and stand-alone functions. For private members and local variables use the GNU naming convention. Constant names should use all uppercase. In a method, use this->member instead of with (this) {.... member....}

Rationale: This is for compatibility with a built-in classes and methods.

[edit] Commens

• All comments shall be written in English.

Rationale: Not everyone is fluent in your native language

• Trivial comments such as in the line

$i++; // here we increment $i

have to be avoided Rationale: Such comments serve no other purpose but to confuse the reader

• It is a good idea to place Doxygen-style documentation before each function

Example:

/** \brief creates a URL from an associative array by imploding togater the key=>value pairs
	\param $array - the array to use for creating the url
	\param $dest_is_html - indicates whether the returned value is to be echoed into 
	                                         HTML source. if so, then is combines values using &amp as a separator, otherwise
                                                only &. (HTML standard requires "&" to be ecoded as "&")
*/
function create_url($array, $dest_is_html=true) 
   ...

Rationale: Not only does this document the code, but it allows us to generate documentation automatically from the source code