Programming: Good style

A few basic remarks on programming, which may well be taken as recommendations.

Code should be written and formatted in a way that is understandable, comprehensible, and easy to read. Keep in mind: It is always possible that an outsider needs to understand your code before they can change it (for whatever reason; help, improvement, customization).

Any fool can write code that a computer can understand.
Good programmers write code that people can understand.

Martin Fowler

Since CMSimple_XH 1.6 the Pear Programming Standards have been adopted for the core system. Extension writers may consider adopting these coding standards as well, but of course this is not mandatory.

Tips

1. Always write <?php … ?> or <?= … ?> – never the short version <? … ?>, because PHP could misinterpret it when parsing.
2. Choose understandable names for functions and variables and avoid – as far as possible – introducing new global variables. For example, prefix your functions with the name of the plugin – this way it is always clear what belongs to what and potential conflicts with other functions are avoided.
3. Indent your code with 4 spaces logically.
4. Use curly braces – even when it would not be necessary. Example:
   

   // bad (this also concerns point #2):
   if ($t == '')e('undefined', 'file', $fl);
   
   // better:
   if ($temp == '') {
       error_message('undefined', 'file', $file);
   }​
   

5. Use single quotes, at least in case there is nothing to evaluate in the string. Example:
   

   // bad:
   echo "<a href=\"https://www.cmsimple-xh.org\" title=\"CMSimple_XH\">CMSimple_XH</a>";
   
   // better:
   echo '<a href="https://www.cmsimple-xh.org" title="CMSimple_XH">CMSimple_XH</a>';​

6. Separate parameters and operators with spaces. Example:
   

   // bad:
   function some_function($foo,$bar){
       if($foo==bar){
            return $foo+$bar;
       }
   }
   
   // better:
   function some_function($foo, $bar) {
       if($foo == bar) {
           return $foo + $bar;
       }
   }​

7. In case of many parameters or conditional clauses, use line breaks and indentation. Example:

   // bad:
   if(isset($foo) && $foo > 1 && $foo < 45 && $bar == true){
       //...
   }
   
   // better:
   if(isset($foo)
       && $foo > 1
       && $foo < 45
       && $bar == true
   ) {
       //...
   }

8. Do not nest too deeply, and write short lines of code (max. 80 characters). Example:
   

   // 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);​
   ...

   For short lines: Place the concatenation points in multiple lines just below the =. Example:

   // bad:
   $foo = $foo1.$foo2.$foo3.(my_super_cool_calculation).etc;
    
   // better:
   $foo = $foo1
        . $foo2
        . $foo3
        . (my_super_cool_calculation)
        . etc;

9. Function names are better too long than too short. A descriptive phrase as a function name makes the code easier to understand. Start with a lowercase letter and separate words with camelCase or underscores.

   // bad
   function myownfunctin() {
       ...
   }
   // better - camelCase
   function myOwnFunction() {
       ...
   }
   // even better: plugin name + underscore + camelCase combined
   function myPlugin_myOwnFunction() {
       ...
   }​

10. Class definitions should start with a capital letter and have a newline before the opening parenthesis.

    class Toy
    {
        //...
    }

11. Insert mappings into arrays.

    // bad:
    array('drink' => 'coffee', 'do_not_watch'=>'tv','eat'=>'bread');
    
    // better:
    array(
        'drink'        => 'coffee',
        'do_not_watch' => 'tv',
        'eat'          => 'bread',
    );

12. Last but not least, comment extensively wherever and whenever appropriate!
    You don't have to worry that anything runs slower because of too many comments – i.e. performance suffers. Comments are ignored by PHP and will not be transmitted! HTML or JavaScript comments are transmitted, but the gain in clarity outweighs them.