You are here: start » coding_style

Coding Style

Code in a way that helps others to understand your code. Any fool can write code that a computer can understand. Good programmers write code that humans can understand.(Martin Fowler)

Since CMSimple_XH 1.6 the pear coding standards have been adopted for the core. Extension writers may consider adopting these coding standards also, but of course that is no requirement.

Because some people get religious when talking about their coding style, don't take this list as something like the Ten Commandments, but just as ten suggestions to increase readibility of your plugins and addons.

  1. Alway use <?php ?>, never the shorthands <? ?> or <?= ?>.
  2. Choose understandable names for functions and variables and avoid using new global variables as far as possible. And prefix your functions with e.g. the plugin's name (because we can't use namespaces for compatibility with PHP < 5.3).
  3. Indent your code with 4 spaces or tabs 4 spaces long in a logical manner.
  4. It is recommended to use curly brackets, even if they are not required.
    // bad (concerning point #2 as well):
    if ($t == '')e('undefined', 'file', $fl);
     
    // better:
    if ($temp == ''){
       error_message('undefined', 'file', $file);
    }
    // or:
    if ($temp == '')
    {
       error_message('undefined', 'file', $file);
    }
  5. Use single quotes, at least in case when there is nothing to evaluate in the string.
    //bad:
    echo "<a href=\"http://www.cmsimple-xh.org\" title=\"CMSimple_XH\">CMSimple_XH</a>";
    //better:
    echo '<a href="http://www.cmsimple-xh.org" title="CMSimple_XH">CMSimple_XH</a>';
  6. Separate parameters and operators with spaces
    // bad:
    function some_function($foo,$bar){
        if($foo==bar){
             return $foo+$bar;
        }
    }
    // better:
    function some_function($foo, $bar){
         if($foo == bar){
             return $foo + $bar;
        }
    }
    // or:
    function some_function($foo, $bar)
    {
        if($foo == bar)
        {
            return $foo + $bar;
        }
    }

    If there are a lot of parameters or conditions use linebreaks and indentation.

    // bad:
    if(isset($foo) && $foo > 1 && $foo < 45 && $bar == true){
        //...
    }
    // better:
    if(    isset($foo)
        && $foo > 1
        && $foo < 45
        && $bar == true
    ) {
        //...
    } 
  7. Do not nest too many things, and write short code lines (max. 80 characters is usually recommended).
    // bad:
    $foo = explode('§', preg_replace("/(<h[1-".$cf['menu']['levels']."][^>]*>)/i", \\1", str_replace('§', '&#167;', rf($pth['file']['content']))));
     
    // better: 
    $foo = rf($pth['file']['content']);
    $foo = str_replace('§', '&#167;' $foo);
    $foo = preg_replace('/(<h[1-'
         . $cf['menu']['levels']
         . '][^>]*>)/i', '§\\1', $foo);
    $foo = explode('§', $foo);   

    While writing short lines place the concatenation dot in multiple lines exactly under the “=“

    // bad:
    $foo = $foo1.$foo2.$foo3.(my_super_cool_calculation).etc;
     
    // better: 
    $foo = $foo1
         . $foo2
         . $foo3
         . (my_super_cool_calculation)
         . etc;
  8. Function names are better too long than too short. A descriptive phrase as function name makes understanding the code easier. Start with lower case letter and separate words using camelBack or underscores.
  9. Class definitions should start with uppercase and have a linebreak before the opening bracket.
    class Toy
    {
       //...
    }
  10. Indent the assignments in arrays.
    // bad:
    array('drink' => 'coffee', 'do_not_watch'=>'tv','eat'=>'bread');
     
    // better:
    array(
        'drink'        => 'coffee',
        'do_not_watch' => 'tv',
        'eat'          => 'bread',
    );
 
You are here: start » coding_style
Except where otherwise noted, content on this wiki is licensed under the following license: GNU Free Documentation License 1.3
Valid XHTML 1.0 Valid CSS Driven by DokuWiki