View source for Coding Guidelines

== Coding Guidelines for Geeklog 1.4. ==

Geeklog 1.x never had any formal coding guidelines so you may find different styles in different places. This is an attempt to pull things together again slightly and help avoid further diversification ...

'''Why have Code Conventions?'''

To quote from the [[Coding_StandardsG2|Geeklog 2 Coding Standards]]:

Code conventions are important to programmers for a number of reasons:

* 80% of the lifetime cost of apiece of software goes to maintenance.
* Hardly any software is maintained for its whole life by the original author.
* Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.


=== Code Layout ===

==== Indentation ====

As it says on the top of nearly all of Geeklog' .php files: ''Reminder: always indent with 4 spaces (no tabs).''

==== Comments ====

Single-line comments should always use the // comments separator. Multi-line comments can consist of either consecutive lines all using the single-line comment separator or they can use /* ... */


<pre>// this is a single-line comment

/* while this
 * is a multi-line comment
 */

// but this
// is also a multi-line comment</pre>

Function header should always be preceeded by a PHPDoc-like function description using the /** ... */ style (note the extra '*'):

<pre>/**
* This function does some cool stuff
*
* @param   string   $entry   the entry's text
* @param   int      $value   the corresponding value, max. range 0..42
* @return  bool              returns true for valid entries
*
*/</pre>


==== Main ====

PHP files that are not meant to be included should have a "main" section near the ''end'' of the file that is to be clearly marked as such, e.g. with a comment like this:

<pre>// MAIN</pre>

The implementation of all functions local to this .php file should go above the main section.


=== Brackets and Spacing ===

Over time, two main styles for placing brackets and spaces have developed: The one used in lib-common.php, that has since been begun to be picked up by some (but not all) the system/lib-*.php files and the style used in almost all the other files.

When adding or editing code, make sure to pick up the style of the surrounding code. There is nothing more irritating than trying to read some piece of code that switches back and forth between various coding styles.


==== The two styles compared ====

The style used in lib-common.php is more "spacious" and looks something like this:

<pre>    if(( $arg1 == 42 ) || ( $arg2 > 23 ))
    {
        $result = call_function( $arg1, $arg2 );
    }
    else
    {
        $result = call_other_function( $arg1, $arg2 );
    }</pre>

i.e. opening curly brackets go on their own line and there's a space after opening and before closing round brackets.

The style used elsewhere is more compact:

<pre>    if (($arg1 == 42) || ($arg2 > 23)) {
        $result = call_function ($arg1, $arg2);
    } else {
        $result = call_other_function ($arg1, $arg2);
    }</pre>

i.e. the opening curly bracket goes at the end of the line that opens the code block (exception: function headers). There is no space after open or before closing round brackets (the space between the function name and the brackets is optional).