1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

[Docs] Use the PEAR Coding Standards

Discussion in 'Developing Plugins' started by Nick, Aug 10, 2009.

  1. Nick

    Nick Well-Known Member

    Drupal and Wordpress both have a list of guidelines based on the PEAR Coding Standards: Drupal Coding Standards | Wordpress Coding Standards

    I wish I had followed such guidelines from the beginning, but it would be better to implement them now rather than later so I'm putting further development on hold until the current code is cleaned up and the coding standards become second nature. There may be some PEAR standards that don't apply to Hotaru, in which case I'll add notes to this thread later.

    If you'd like to assist me in tidying up the code, that would be wonderful! :)

    Update: Having made a start on this, it's safer to say *loosely* based on PEAR's coding standards than trying to follow them rigidly. One bonus of all this is that phpDocumentor can generate automatic documentation, which I'll put in these forums when it's all done. (Edit: phpDocumentor wouldn't play nice so I've dropped that idea for now).

    Please note that although the suggested coding standards in the following posts still apply, the code snippets themselves are from an older version of Hotaru.
     
  2. Nick

    Nick Well-Known Member

    Here are the areas I've been cleaning up, and my recommendations for Hotaru CMS Coding Guidelines:

    Function comments

    I'm not eactly sure of the rules, but I've been doing something like this:

    PHP:
    /**
     * Generate either default or friendly urls
     *
     * @param array $parameters an array of pairs, e.g. 'page' => 'about' 
     * @param string $head either 'index' or 'admin'
     * @return string
     */


    Curly braces


    Every conditional statement should have braces. For functions, I've been putting the opening brace on the next line, but not for control structures (if, while, foreach, etc.) unless helpful for readability, e.g.

    PHP:
    function url($parameters = array(), $head 'index')
    {


    Control Structures


    I've been putting a space between if, while, foreach, etc. and the opening bracket. This keeps the code clean and distinguishes conditionals from function calls, e.g.

    PHP:
            if ($head == 'index') {
                
    $url baseurl 'index.php?';
            }


    Globals


    I've been putting a blank line after global declarations, e.g:

    PHP:
    function url($parameters = array(), $head 'index')
    {
        global 
    $post;
        
        if (
    friendly_urls == "false") {


    Constants


    I've capitalized all constants, e.g.

    PHP:
        if (FRIENDLY_URLS == "false") {
        
            if (
    $head == 'index') {
                
    $url BASEURL 'index.php?';
            }


    PHP in HTML


    When using PHP in HTML, I've used semi-colons after every statement, e.g.

    PHP:
    <a href="<?php echo BASEURL?>"><?php echo $lang["example_home"]; ?></a>
     
  3. DamonW

    DamonW New Member

    Guard clauses

    I would like to propose something. I don't recall what it's called and a quick google search didn't help. It's something like 'return first'.

    Basically instead of this

    PHP:
        public function theme_index_replace()
        {
            global 
    $hotaru$cage;
        
            if (
    $hotaru->isPage('search')) {
            
                
    $search_terms $cage->get->getMixedString2('search');
                
                
    $this->search($search_terms);
        
                return 
    true;
                
            } else {
                return 
    false;
            }
            
        }
    You return false first...

    PHP:
        public function theme_index_replace()
        {
            global 
    $hotaru$cage;
            if (!
    $hotaru->isPage('search')) {
                return 
    false;
            }
            
    $search_terms $cage->get->getMixedString2('search');
            
    $this->search($search_terms);
            return 
    true;
        }
    Some people don't like it. I think it makes the code easier to read since you end up with less indentation and less { and }.

    The file this example came out of is /branches/0.6/content/plugins/search/search.php
     
    Last edited by a moderator: Sep 19, 2009
    Nick likes this.
  4. Nick

    Nick Well-Known Member

    Naming conventions

    As of Hotaru 0.6, all classes should use studlyCaps for methods and properties, i.e. no spaces, hyphens or underscores, and capitalize the first letter of all words except the first. (Class names should start with a capital). E.g.

    PHP:
    class ClassName 
    {
        protected 
    classProperty '';

        public function 
    getClassProperty()
        {
            return 
    $this->classProperty;
        }
    }
    Exception: Methods in plugin classes should use studlyCaps except for those triggered by plugin hooks, e.g.

    PHP:
    public function this_is_a_plugin_hook()
    {
        ....
    }

    public function 
    thisIsNotAPluginHook()
    {
        ....
    }
    The reason for this is to help identify plugin hook methods in a plugin class from other functions.
     

Share This Page