Coding Standards

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

Piwik Code Review Process

In Piwik, we believe in tested and readable source code. This is why we review all new code, examining for code readability, general design and efficiency. Here is a list of things to consider while creating your contribution:

• Code Clarity Is your code easy to read? Do you understand what each line and function does immediately after reading them?
• Correctness Have you added unit tests and are they passing? Did you do UI testing to make sure there are no obvious bugs?
• Code Reuse Did you make sure there is no redundancy in your code? Did you make sure your code does not replicate existing functionality? Is there code that you think can be put into an external library or included in Piwik’s core? (If yes to this last one, let us know!)
• Configuration and Constants Does your code use constants that different users may want to change? These constants should be configurable.
• Failure Handling Does your code handle all error conditions, including corner cases? We do not want code with bugs in it.
• Performance Does your code scale well? What happens when there are hundreds of thousands of websites and billions of visits? If there are performance issues, are they easy to fix? We know how hard it can be to scale efficiently, but we would like for Piwik to be as fast as possible.
• Security Are you using the proper 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 it all loaded from a language file?
• View VS Controller Does your php code contain any HTML? If your code outputs data in the browser, the output should be defined in a separate View template file (.tpl).
• GPL Compatibility Are any third-party components/libraries included? Are the licenses for them compatible with GPL v3? This is the license Piwik uses.

PHP File Formatting, Naming Conventions, Coding Style

• The Piwik source code follows the PSR 1 and PSR 2 coding standards. Starting in Piwik 2.0 we will also follow PSR 0.
• Several Piwik devs are using Phpstorm IDE. We have published our customized PSR coding style xml file for Phpstorm if you wish to reuse it.
• Please read PSR 1 & 2 for more information.
• Files in Piwik’s Git repository are stored using Linux EOL markers (LF).
• All source code files are encoded in UTF8.

PHP Configuration for developers

Committed code should not generate php errors or warnings. Applying the following settings to your php configuration will enable you to achieve this goal:

• display_errors = On (php.ini)
• error_reporting = E_ALL | E_STRICT (php.ini)

Include Path

Piwik does not set or depend on the include path. Plugins should rely on the autoloader for classes and use the absolute path convention for other files:

        require_once PIWIK_INCLUDE_PATH . '/folder/script.php';

Security

We have high security standards.
All plugins developers should carefully read the page about Security in Piwik code.

Basic Clean Code recommendations

About classes:

• A class should follow the Single Responsibility Principle.
• Refactor classes and aim for files/classes that are at most 400 lines.
• Avoid classes with both public attributes and getters/setters. Choose to use getters and setters only when they make code easier to read.
• Add “private” keywords to class attributes when forgotten.

About methods and functions:

• A function should follow the Single Responsibility Principle: each function should do only one thing.
• Think if you can refactor the function body into smaller private methods.
• Aim for a maximum of 20-30 lines per method.
• Aim for maximum three function parameters.
• Extract the body of the try {} blocks into their own private method.

Summary: Alan Shalloway has suggested that there are seven principles for writing clean code: cohesion, loose coupling, no redundancy, encapsulation, testability, readability, and focus.

Commenting

In order to be the best web analytics framework, the Piwik source code must be easy to understand. Comments, in addition to general code cleanliness, are very important for achieving this goal.

Comments are a central part of professional coding. Comments can be divided 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 (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.

Despite their importance, comments can sometimes cause information overload – or worse for out of date comments. We should avoid useless or inaccurate comments, including auto generated comments that do not add any value. Rather than writing comments inside a function, it is better to write shorter functions that do only one thing, and are named carefully. A well refactored class made of small methods will be easy to read and will not need many comments.

No duplication

No duplication is a basic and core principle of extreme programming and of writing good code in general. “Once, and only once”, i.e. Don’t Repeat Yourself. Do not duplicate code.

Debug & logging

In Piwik you can easily log debug messages to files, the database or the screen by enabling logging in your config/config.ini.php file. In your code, you can then call Piwik::log($message); to log new messages, or arrays. You can also show the debug output on screen by appending &debug to the URL: this allows you to test and view debug messages only when needed, but still leave debug logging enabled. See the FAQ to enable logging output in Piwik and the various options.

Piwik also comes with a SQL profiler, which reports the time spent by each query, how many times they were called, the total time spent in Mysql vs php, etc. It makes it easier to check the performance and overhead of your new code. See the FAQ to see how enable SQL profiling.

Automated Tests

If you are fixing a small bug or simply modifying the UI, there is usually no need to write new tests. But if you are adding a new feature to Piwik, adding a new API method or modifying a core Archiving or Tracking algorithm, generally it is required to also submit new or updated Unit tests or Integration tests.

For more information about running or creating tests, see tests/README.md.

When naming unit/integration tests, it helps to use the Given, When, Then convention for writing tests.

Tests are critical part of ensuring Piwik stays a stable and useful software platform. We aim to keep test code as clean as production code so it is easy to improve and maintain.

References

In Summary, we like the words of Alan Shalloway who suggested that there are seven code qualities that matter: cohesion, loose coupling, no redundancy, encapsulation, testability, readability, and focus.

For more information:

• How to submit a pull request or a patch?
• Interesting read about hidden costs of a new feature
• GPL compatible licenses
• We also recommend the book “Clean code” by Robert C. Martin (or this video)

See also: List of Features, Consultants, Testimonials, Piwik supporters, Merchandise and Participate in Piwik!