Coding Standards

Version 15, last updated by fonny at November 07, 2011 10:46 UTC

Note : Parts of this document are based on well known coding standards such as PEAR, Zend Framework, Joomla! 1.5

1. Naming Conventions

Class names are always camel cased: KClassName
Class names are [Prefix]Base[Suffix], where prefix is the namespace, (Com, Mod, or Plg).
Class methods always start with a lowercase, while subsequent parts have an uppercase: myClassMethod()
Variables are lowercased and use underscores: $my_var
Directory and file names are always lowercased. The directory structure represents the name of the class: my/class/abstract.php contains the MyClassAbstract class
Constants are always uppercased and use underscores. Wherever possible, constants are declared inside a class definition. MyClass::MY_CONSTANT
Table names start with the placeholder prefix #__ (two underscores) and use lowercased names with underscores. The name is plural. #__my_items

Note : The 'K' prefix is reserved for Koowa core libraries only. Developers who wish to develop their own libraries need to use their own prefix and implement a custom factory and KFactory and KLoader adapter.

2. Unified constructors

All constructors will (optionally) accept an array of options or KConfig (still to be implemented) object as the first argument. This allows for more flexibility to add new arguments to the constructor, have variable numbers of arguments, and allow “named” arguments. Additionally, it’s a good technique for allowing

3. Dependency Injection.

Example:

  protected function __construct(KConfig $config)
 {
    // ...
 }

Note : Config keys should always use a all_lowercase_underscore_keys syntax.

Note: Usually Nooku Framework objects are instantiated via KService::get(), not via direct instantiation. KService will pass the options to the constructor.

4. KService methods

KService methods are used to create and return objects. KService methods are often used as shortcuts. Shortcuts are an antipattern, they make an API harder to use and understand. We value less code, but not not at the expense of a clear API.

In Nooku Framework KService methods will not create the actual object but only return an object identifier, the responsibility to create the objects lies with the calling code.

An example

// KControllerBread::_actionBrowse()
echo KService::get($this->getView())
    ->setLayout($layout)
    ->display();

In other words, $this->getView() now doesn't return a KView object, but only an identifier referring to a KView object, eg com://admin/foo.view.bar. You feed the identifier to KService and have it create or return your view object.

In your client code, many of you used to do something like this:

class FooControllerBar extends KControllerBread
{
    protected function _actionBrowser()
    {
        // ... some stuff ...
        echo KService::get('...mycustomviewobject')
            ->setLayout($layout)
            ->display()
    }
}

The golden rule : whenever you know the exact name of the object you want, use it! Don't copy Nooku code to build it dynamically, but just type out the identifier. Nooku has a lot of complicated code, so that you wouldn't have to.

The getters function definition now carry the 'final' keyword, so you can't override them anymore. These changes will break some code.

The following getter methods return an identifier :

KControllerAbstract::getView()
KControllerAbstract::getModel()
KModelTable::getTable()
KViewAbstract::getModel()
KViewDefault::getToolbar()

5. Writing SQL

If you find yourself writing raw SQL, make sure to write keywords and functions in uppercase, like for instance this:

SELECT 
    title AS name, 
    COUNT(*) AS num_messages, 
    CONCAT_WS(' ', first_name, last_name) AS name 
FROM private_messages

If you don't, the code will fall victim to aggressive quoting:

count(*) AS num_messages

will turn into

`count`(*) AS num_messages

…and consequently fail.

6. Inline Documentation

DocBlocks

PhpDocumentor tags are used. There's a block at the top of the file, for classes, class properties and constants, methods, functions.

A package usually corresponds with a root level folder, and is prefixed with Koowa, as in @package Koowa_Model
A subpackage usually corresponds with a file or folder one level down.

Other comments

With some carefully chosen comments, a block of code can be made easily readable, without the need to decipher what the code is about. When something is not immediately obvious, explain it in some more detail.

7. use / (forward slash) as a directory separator

Do not use a constant like DS. There is no need for it anymore, as PHP takes care of rendering it differently if needed, for instance as \ (backward slash) on a Windows filesystem.

For a discussion about it in Joomla! 1.5 and 1.6 see:

8. Indenting and Line Length

Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, SVN history and annotations. It is recommended to keep lines at approximately 75-85 characters long for better code readability.

9. No closing ?>

PHP will stop when it reaches a closing ?> or the end of the file. So a closing ?> is not necessary. If there is whitespace after the ?> this will be rendered to the browser, either before the headers are complete or before the start of the page, either of which can cause problems and be very difficult to locate.