Coding standard

This document provides the code guidelines for developers and teams contributing to Piwik

  1. Coding standard
    1. Piwik Code Review Process
    2. SVN Configuration
    3. PHP File Formatting
    4. Naming Conventions
      1. Class naming
      2. Filenames
      3. Functions and Methods
      4. Variables
      5. Constants
    5. Coding style
    6. Security
    7. Commenting
    8. References

Piwik Code Review Process

In Piwik, we believe in beautiful, tested and readable code source. This is why we try to review every new code on the SVN in terms of code readability, general design, efficiency. Here is a list of general aspects to consider during the code review:

  • Code clarity

Is it easy to read? Do you understand what each line and function does at a glance? If not, it's too complicated.

  • Correctness

Are there obvious bugs? Are there unit tests and have they been run?

  • Reuse and Duplicated Code

Is code duplicated within the package? Is there local functionality that exist already, or that should be in a library? If yes, please let the team know about these requirements.

  • Configuration and Constants

Does behavior switch on arbitrary constant values that should be configurable?

  • Failure Handling

Does the code handle edge cases? Does the code handle just the happy path or does it consider and handle all error conditions?

  • Performance

Are there obvious performance or efficiency problems that are trivial to address?

  • Security

Are you using the  helper method to retrieve GET or POST variables? Are you properly checking for user permissions to restrict data access?

  • i18n

If your plugin contains text, is all the text loaded from the language file?

  • View VS Controller

Does your php code contain any HTML? If your code outputs data in the browser, it should be separated in a View template file (.tpl).

SVN Configuration

Please edit your local SVN configuration file following this page:  https://developer.openx.org/wiki/display/COMM/Configuring+Subversion

PHP File Formatting

  • Use a tabulation indent with a width of 4 spaces. Do NOT use spaces!
  • The maximum length of any line of PHP code is 120 characters.
  • Line termination is the standard way for Unix text files.
    Do not use carriage returns (CR) like Macintosh computers.
    Do not use the carriage return/linefeed combination (CRLF) as Windows computers
  • All source code files are encoded in UTF8.

Naming Conventions

Class naming

Class names may only contain alphanumeric characters. Numbers are permitted in class names but are discouraged.

If a class name is comprised of more than one word, the first letter of each new word must be capitalized.

These are examples of acceptable names for classes: 

Piwik_Common
Piwik_Plugin
Piwik_ViewDataTable_Cloud

When developping plugins, the plugin classes (main class, controller, optional API) must respect a naming style documented in the  Plugins development documentation.

Filenames

For all other files, only alphanumeric characters, underscores, and the dash character ("-") are permitted. Spaces are prohibited.

Any file that contains any PHP code must end with the extension ".php".

These examples show the acceptable filenames for containing the class names from the examples in the section above: 

modules/Common.php
modules/Plugin.php
modules/ViewDataTable/Cloud.php

Functions and Methods

Function names must always start with a lowercase letter. When a function name consists of more than one word, the first letter of each new word must be capitalized. This is commonly called "camelCase" formatting.

Verbosity is encouraged. Function names should be as verbose as is practical to enhance the understandability of code.

For object-oriented programming, accessors for objects should always be prefixed with either "get" or "set". When using design patterns, such as the singleton or factory patterns, the name of the method should contain the pattern name where practical to make the pattern more readily recognizable.

These are examples of acceptable names for functions: 

filterInput()
getElementById()
widgetFactory()

Variables

Variable names may only contain alphanumeric characters. Underscores are not permitted. Numbers are permitted in variable names but are discouraged.

Verbosity is encouraged. Variables should always be as verbose as practical. Terse variable names such as "$i" and "$n" are discouraged for anything other than the smallest loop contexts. If a loop contains more than 20 lines of code, the variables for the indices need to have more descriptive names.

Constants

Constants may contain both alphanumeric characters and the underscore. Numbers are permitted in constant names.

Constants must always have all letters capitalized.

Coding style

  • PHP code must always start with the full-form, standard PHP tag: 
    <?php
  • PHP files should not end with ?>. If you write ?> and accidentally leave a blank space after, this would cause the "headers already sent" classic error. It is valid to not end php files with the ?> and this is mandatory practise for Piwik files.
  • Class Declaration 
    /**
 * Documentation Block Here
 */
class SampleClass
{
    // entire content of class
    // must be tabulation indented 
}
  • If / else statements 
    if ($a != 2)
{
    $a = 2;
} 
else 
{
    $a = 7;
}

Security

We have high security standard in Piwik.

All new code and all plugins developpers should read carefully the page about the Security in Piwik code.

Commenting

In order to be the reference web analytics framework, Piwik source code must be easy to understand. Comments are very important to achieve this goal, as well as general code quality.

Comments are a central part of professional coding practice. We can divide comments into three categories: documentary, serving the purpose of documenting the evolution of code over time, functional, helping the co-ordination of the development effort inside the team and explanatory comments, generating the software documentation for general use. All three categories are vital to the success of a software development project. (from  The fine Art of Commenting)

For an example of a well commented Piwik class, see Piwik_Cookie.

References