When reviewing code, the first step is to know what has to be checked, and what will be considered for fixing. There are lots of considerations to be taken into account, and it is often difficult to both agree on which code smells to check, and to collect all of them in the same time. ClearPHP aims at solving this last problem : collect all recommendations, and have them available as a reference.
A reference for good code
Sources of inspirations for rules included in clearPHP are several
- PHP manual itself. It has its own recommendations, such as the userland naming rules, Comparison (big warning about floating point comparison), or warnings about strpos() and friends.
- PHP version migrations, also detailed in the appendices of the manual. They require a dose of code review.
- Computer science recommendations, such as the classic for optimization (for($i = 0 ; $i < count($array) ; $i++) {…}
- Performances and security recommendations. Those tends to be presented with general concepts. ‘filter input, escape output’ is always a good recommendation, but it may be difficult to understand how to apply it.
- Experience gained from reviewing code, discussing with community and other fellow developers.
Code smells, not coding convention
Currently, code audits will use coding convention, which focuses on how the code is written. That means variable naming scheme, indentation, operator’s spacing, etc. Some of the rules listed here will arguably fall into this category, though clearPHP reference aims at referencing code smells rather than coding conventions. For example, bracketless control structure are considered as coding convention, and is also part of this reference as a bug source.
On the other end, checking code for cleanness stops when it reach conception choices. Those choices are made in relation with the business logic or a higher level of abstraction. This is were features and bugs are sorted out. At that point, the influence of auditing coding is limited.
Choose your own reference
Such reference will be quite big. It is already and keeps growing. It is impossible to apply all those rules at the same time : first because it will take too long to apply ; secondly, because rules might be contradictory. This is not critical, as choosing a set of them is the most important. It capture the spirit of coding for one product or application. You are encouraged to choose any set of rules that you feel will apply, and just ignore the rest.
ClearPHP is a work in progress, and PR on github will be welcome, so as discussions about the content itself. Enjoy.