This document provides the coding guidelines for developers and teams contributing to Piwik.
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:
Committed code should not generate php errors or warnings. Applying the following settings to your php configuration will enable you to achieve this goal:
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';
We have high security standards.
All plugins developers should carefully read the page about Security in Piwik code.
About methods and functions:
Summary: Alan Shalloway has suggested that there are seven principles for writing clean code: cohesion, loose coupling, no redundancy, encapsulation, testability, readability, and focus.
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 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.
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.
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.
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: