Use the PEAR Coding Standards

[Nick]

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.

[Nick]

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:

/**
 * 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.

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.

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

Globals

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

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

Constants

I've capitalized all constants, e.g.

    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.

<a href="<?php echo BASEURL; ?>"><?php echo $lang["example_home"]; ?></a>

[DamonW]

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

    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...

    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

[Nick]

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.

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.

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.