Coding style

Discussions and requests related to new CMSimple features, plugins, templates etc. and how to develop.
Please don't ask for support at this forums!
Post Reply
Martin
Posts: 346
Joined: Thu Oct 23, 2008 11:57 am
Contact:

Coding style

Post by Martin » Wed Jan 20, 2010 8:53 pm

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
Posts: 116
Joined: Wed Dec 09, 2009 12:33 pm
Location: Kloetinge, Netherlands
Contact:

Re: Coding style

Post by leenm » Wed Jan 20, 2010 9:10 pm

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
Posts: 3586
Joined: Tue May 20, 2008 5:34 am
Location: Slovakia
Contact:

Re: Coding style

Post by Tata » Wed Jan 20, 2010 9:29 pm

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.
CMSimple.sk
It's no shame to ask for an answer if all efforts failed.
But it's awful to ask without any effort to find the answer yourself.

leenm
Posts: 116
Joined: Wed Dec 09, 2009 12:33 pm
Location: Kloetinge, Netherlands
Contact:

Re: Coding style

Post by leenm » Wed Jan 20, 2010 9:42 pm

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

Gert
Posts: 3078
Joined: Fri May 30, 2008 4:53 pm
Location: Berlin
Contact:

Re: Coding style

Post by Gert » Thu Jan 21, 2010 8:10 am

Hi Martin,

your code-conventions should be copied to the DokuWIKI: start » deutsch » entwicklerdokumentation » plugins » code_conventions
Gert Ebersbach | CMSimple | Templates - Plugins - Services

Holger
Site Admin
Posts: 3470
Joined: Mon May 19, 2008 7:10 pm
Location: Hessen, Germany

Re: Coding style

Post by Holger » Thu Jan 21, 2010 11:23 am

leenm wrote:If Martin gathers all the "rules" in the first post, we have a nice overview.
+1
Gert wrote: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
Posts: 14225
Joined: Tue Jun 21, 2011 11:04 am
Location: Bingen, RLP, DE
Contact:

Re: Coding style

Post by cmb » Fri Jul 01, 2011 9:24 am

Hello developers,
Martin wrote: 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.
tata wrote: 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().
Christoph M. Becker – Plugins for CMSimple_XH

cmb
Posts: 14225
Joined: Tue Jun 21, 2011 11:04 am
Location: Bingen, RLP, DE
Contact:

Re: Coding style

Post by cmb » Thu Jul 28, 2011 1:56 pm

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.:
§7 wrote: 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.
§4 wrote: 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.
:lol:

Christoph
Christoph M. Becker – Plugins for CMSimple_XH

cmb
Posts: 14225
Joined: Tue Jun 21, 2011 11:04 am
Location: Bingen, RLP, DE
Contact:

Re: Coding style

Post by cmb » Wed Jul 31, 2013 6:18 pm

The coding styles are now available under Start -> Developers Manual -> Plugins -> Coding Style.
Christoph M. Becker – Plugins for CMSimple_XH

Post Reply