bit3 coding standards
These are our coding standards., (*1)
This coding standard based on the great TYPO3 coding standard, see
http://forge.typo3.org/projects/team-php_codesniffer/wiki/Using_the_TYPO3_Coding_Standard, (*2)
Philosophy
Our philosophy: Write fast readable and comprehensible code.
Don't be shy to write more lines, if it makes each line more atomic., (*3)
What is the benefit of atomic lines?
When each line is full atomic (only contains one operation), the order of lines reflect the execution order of the commands., (*4)
When you have a complex line like this:, (*5)
$variable = ($foo != $bar && count($zap) || $dig) ? $this->func($zap, $foo, $bar) : $this->other(count($zap))->chain($foo, $bar);
How is the order of execution? What do this code? You can understand if you analyse the line, but its hard to do.
Simplified this is the execution order of the operations:, (*6)
evaluate $foo != $bar
execute count($zap)
evaluate count($zap)
evaluate .. && ..
evaluate $zip
evaluate .. || ..
if true
execute $this->func($zap, $foo, $bar)
else
execute count($zap)
evaluate count($zap)
execute $this->other(count($zap))
execute $..->chain($foo, $bar)
assign $variable
If you want to understand what this code do, you have to understand the execution order of the operations and the meaning of each operation.
If you write this in a more atomic style, you make it easier to understand, for others and yourself if you nod touch the code a long time!, (*7)
Compare against this, it is exactly the same code:, (*8)
if (
$foo != $bar && count($zap) ||
$dig
) {
$variable = $this->func($zap, $foo, $bar);
}
else {
$variable = $this->other(count($zap))->chain($foo, $bar);
}
As you can see, this snippet more reflect the execution order and it is much easier to understand what it do., (*9)
Usage
Install the coding standards via composer:, (*10)
"require-dev":{
"bit3/php-coding-standard":"@dev"
}
After updating dependencies, copy the example ant build file from vendor/bit3/php-coding-standard/example/build.xml into your project.
If your sources are not in src/, change the path to your sources in the build file., (*11)
Hint: If you not use phpunit, remove the phpunit target from build file., (*12)
You can run the tests by invoke ant phpmd and ant phpcs.
Running ant or ant test will run all test targets., (*13)
Hint: To run all testes, even if one fail, use ant -keep-going., (*14)
Definitions
-
long line means a line that is longer than 60 characters.
- No line should be longer than 100 characters.
- No line must be longer than 120 characters.
Files
No file must contain more than one class, interface or function.
The file name must the same (including case) as the class, interface or function named defined in it.
Without any prefix (e.g. class.) or suffix (e.g. .inc), expect the the file type extension .php., (*15)
Runner scripts, should contain a runner class, containing a run method., (*16)
Example index.php:, (*17)
<?php
require_once('autoload.php');
class index
{
public function run()
{
// runtime code
}
}
$index = new index();
$index->run();
Hint: Runner classes must not be in pascal-case, but must match the file name., (*18)
Second example ajax.php, (*19)
<?php
class ajax
{
public function run()
{
// runtime code
}
}
$ajax = new ajax();
$ajax->run();
Whitespaces
Do not use SPACE for indention. Use TAB., (*20)
Add spaces to split operators:
* assignment: $variable = 'value'
* parameters: func($a, $b, $c)
* arrays: array('foo' => 'bar', 'bar' => 'foo')
* comments: // comment or * multiline comment, (*21)
Class and function declaration
Place opening brace { on new line for all non-control-structures like class or function declaration.
Place extends and implements on new line and indent one time., (*22)
class Foo
extends Bar
implements Zap
{
public function func()
{
...
}
}
function func()
{
...
}
Don't add a space before opening bracked ( in function declarations or calls., (*23)
Naming
Use pascal-case class names., (*24)
// bad
class foo_bar {
}
// good
class FooBar {
}
Use camel-case method names., (*25)
// bad
function foo_bar() {
}
// good
function fooBar() {
}
Control structures
Place opening brace { on same line for all control-structures.
Add newline after closing brace }, even the control-structure continues., (*26)
if (...) {
...
}
else if (...) {
...
}
else {
...
}
for (...) {
...
}
foreach (...) {
...
}
while (...) {
...
}
do {
...
}
while (...);
Why putting the else on a new line?
It's simple, first it is the beginning of a new block. Second it is easier to make comments that describe the conditions., (*27)
// describe if condition
if (...) {
...
}
// describe else if condition
else if (...) {
...
}
// describe else condition
else {
...
}
Long and multiline conditions
If control-structure condition gets to long, place closing bracket and opening brace ) { in a separate line and place condition in separate line., (*28)
if (
... very long ...
... multiline ...
) {
...
}
else if (
... very long ...
... multiline ...
) {
...
}
else {
...
}
for (
... very long ...
... multiline ...
) {
...
}
foreach (
... very long ...
... multiline ...
) {
...
}
while (
... very long ...
... multiline ...
) {
...
}
do {
...
}
while (
... very long ...
... multiline ...
);
Don't forget the whitespace before opening bracket (., (*29)
Ternary operator
When using ternary operator, you should put then and else part in separate lines and indent one time if line gets longer., (*30)
// good
$variable = $if ? $then : $else;
// good
$variable = $if ? $this->then() : $this->else();
// bad
$variableObjectname = $someLongVariable != $otherLongVariable ? $veryLongVariableName : $anotherVeryLongVariableName;
// good
$variableObjectname = $someLongVariable != $otherLongVariable
? $veryLongVariableName
: $anotherVeryLongVariableName;
Ternary operator should only be used for simple left/right decisions. Do not use in combination with complex conditions or logic., (*31)
// bad, use formated if-statement instead
$variable = $firstVariable != $secondVariable && someCheckFunction($variableName) || anotherCheckFunction($thirdVariable)
? $this->someComplexFunction($firstVariable, $secondVariable, $thirdVariable)
: 'some string prefix ' . substr($this->otherComplexFunction($variablename), 0, strlen($thirdVariable)) . ' some string suffix';
// good
$variable = $firstVariable != $secondVariable ? $this->then() : $this->else();
// good
$variable = someCheckFunction($variableName) ? $then : $else;
Function/Method calls
In function/method calls use space to split parameters, but do not add space before opening bracket (., (*32)
// bad
func ('a','b','c');
// good
func('a', 'b', 'c');
When parameter list gets long, make it multiline and put every parameter on a singleline.
Also put the closing bracket ) on a singleline., (*33)
// bad
func ('short', 'short',
'very long param');
// good
func(
'short',
'short',
'very long param'
);
When chain method calls, put each method call in separate line if it make sense or the line gets to long., (*34)
// bad
$database->prepare('SELECT a,long,list,of,fields FROM some_table WHERE some_complex_and_long_where')->limit(100)->offset(50)->execute();
// a little bit better
$database->prepare('SELECT a,long,list,of,fields FROM some_table WHERE some_complex_and_long_where')
->limit(100)->offset(50)->execute();
// good
$database
->prepare('SELECT a,long,list,of,fields FROM some_table WHERE some_complex_and_long_where')
->limit(100)
->offset(50)
->execute();
Variables
Initialisation
Make complex array initialisations multiline and put every element in single line., (*35)
$array = array(
'item1',
'item2',
'item3',
);
$array = array(
'index1' => 'item1',
'index2' => 'item2',
'index3' => 'item3',
);
Naming
Use camel-case variable names.
Use significant variable names instead type prefix., (*36)
// bad
$intUser = 1;
// good
$userId = 1;
// bad
$objUser = ...some object...;
// good
$user = ...some object...;
// bad
$arrUsers = array(1, 2, 3);
// good
$userIds = array(1, 2, 3);
// bad
$arrUsers = array(...object..., ...object..., ...object...);
// good
$users = array(...object..., ...object..., ...object...);
Logic
Keep every line as simple as possible, do not combine to many operations in one line.
Use readable control structures if needed, even you write a lot more lines!, (*37)
// bad
$variable = ($foo != $bar && count($zap) || $dig) ? $this->func($zap, $foo, $bar) : $this->other(count($zap))->chain($foo, $bar);
// good
$n = count($zap);
if (
$foo != $bar && $n ||
$dig
) {
$variable = $this->func($zap, $foo, $bar);
}
else {
$variable = $this->other($n)->chain($foo, $bar);
}
Don't use logic in function call parameters., (*38)
// bad
func(
$if
? $then
: $else,
'foo',
other('bar')
);
// good
$param = $if
? $then
: $else;
$other = other('bar');
func(
$param,
'foo',
$other
);
Use function or method chaining with caution, but keep it as simple as possible., (*39)
// avoid illogical chaining
// $this->func, strlen and file_get_contents does not logical belongs to each other
$this->func(strlen(file_get_contents('/some/file')));
// better
$content = file_get_contents('/some/file');
$this->func(strlen($content));
// best
$content = file_get_contents('/some/file');
$length = strlen($content);
$this->func($length);
// be gentle with logical chaining
// the array_* functions are logical belongs to each other,
// but its hard to understand this at a glance
$result = array_values(array_filter(array_map('trim', $array)));
// better
$result = array_values(
array_filter(
array_map(
'trim',
$array
)
)
);
// best, keep it simple, fast readable and more comprehensible - and it is short :-)
$result = array_map('trim', $array);
$result = array_filter($result);
$result = array_values($result);
Wallogit.com
