Coding standard

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

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
  • 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 and the generated documentation of this class.

References