Coding style

[Martin]

CMSimple has it's origin in a perl script. Perhaps that's the reason why, some parts of the core code are not that easy too read as it could be. There are a good 60 plug-ins by different authors with different coding styles. In my opinion we should try to get the things more consistent and comprehendible. I know, that some people get religious when talking about their coding style, so don't take this list as something like the Ten Commandments. Just ten suggestions to increase readibility (-> effectivity of collaboration):

1. Alway use <?php ?>, never the shorthands <? ?> or <?= ?>
2. Choose understandable names for functions and variables.
3. Indent your code with tabs in a logical manner.
4. Use curly brackets, even if they are not required

   Code: Select all

   //BAD example (for point #2 as well)
if ($t == '')e('undefined', 'file', $fl);

// better:
if ($temp == ''){
   error_message('undefined', 'file', $file);
} 

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

   Code: Select all

   //bad:
echo "<a href=\"http://www.cmsimple.org\" title=\"CMSimple\">CMSimple</a>";
//better:
echo '<a href="http://www.cmsimple.org" title="CMSimple">CMSimple</a>'; 

6. Separate parameters and operators with spaces

   Code: Select all

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

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

   Code: Select all

   //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 don't write code lines with more than about 80 characters.

   Code: Select all

   //bad:
$foo = explode('§', preg_replace("/(<h[1-".$cf['menu']['levels']."][^>]*>)/i", "§\\1", str_replace('§', '&#167;', rf($pth['file']['content']))));

//better: (not good anyway, but at least better to understand)
$foo = rf($pth['file']['content']);
$foo = str_replace('§', '&#167;' $foo);
$foo = preg_replace('/(<h[1-'.$cf['menu']['levels'].'][^>]*>)/i', '§\\1', $foo);
$foo = explode('§', $foo);
 

8. Function names should start with a lower case letter, the single words should be separated from each other. (But what is better camel cased (myFunction())  or the underscore solution (my_function()?)
9. Class definitions should start with an uppercase and have a linebreak before the opening bracket

   Code: Select all

   class Toy
{
   //...
} 

10. Indent the assignments in arrays:

    Code: Select all

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

Discussions and additional ideas are welcome!

Martin

[leenm]

11. Document you code. Preferably compatible with the phpDocumentor format.

It's a good idea to use the same coding style. Mostly I follow the Zend Framework Coding Standard for PHP.

Leen

[Tata]

IMHO excellent 10C!
This way more authors may born and also many potential authors will born. It will be easier to understand the code and eventually look for bugs in it. This "basic coding grammar rules" should be written somewhere with red capitals. Maybe a section "Write your own plugin" or similar should be a part of Developers' Manual (?). I have not seen djot in this forum, but he had an excellent tutorial_example_plugin. this would be an excellent start point showing not only these "10C" but also the basics of plugin basic structure and requirements.

[leenm]

If Martin gathers all the "rules" in the first post, we have a nice overview.

[Gert]

Hi Martin,

your code-conventions should be copied to the DokuWIKI: start » deutsch » entwicklerdokumentation » plugins » code_conventions

[Holger]

If Martin gathers all the "rules" in the first post, we have a nice overview.

+1

your code-conventions should be copied to the DokuWIKI: start » deutsch » entwicklerdokumentation » plugins » code_conventions

For now I made a sticky of this post.

BTW: I promise to take care on the "rules" .

Holger

[cmb]

Hello developers,

In my opinion we should try to get the things more consistent and comprehendible

Thanks for giving this to the developer community. It's IMHO invaluable to have coding conventions, to better be able to read and modifiy other's code.

Some minor suggestions:
§2. 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)
§6. Exception: string concatenation. I've seen it's common to skip the spaces to avoid too long lines (§8)
§8. AFAIK the general PHP convention is to use _ for function names and camelCase for methods.

Maybe a section "Write your own plugin" or similar should be a part of Developers' Manual

I'm currently trying to put together such a tutorial for the XH-Wiki.

Christoph

PS: Should the use of PHP_EOL instead of "\n" be considered? I don't think that there might be any problems with using "\n" (most installations run under *nix anyway, and even IIS should have no problems with "\n"). But I like PHP_EOL more when reading and writing code. Currently I'm not using PHP_EOL, because nobody seems to do and I could imagine problems with e.g. rmnl().

[cmb]

Hello developers,

I've just put Martin's suggested coding style to the XH-Wiki.

Perhaps the wording should be slightly adjusted to have more impact on developers. E.g.:

Thou shalt not nest too many things, nor shalt thou write code lines with more than about 80 characters, for chaos and madness await thee in the end.

Thou shalt use curly brackets, even when thou art convinced that this is unnecessary, lest they take cruel vengeance upon thee when thou least expect it.

Christoph