From 251f6446d14b0b8db30a562d5643f2ac79909034 Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Thu, 3 May 2012 00:31:01 +0400 Subject: [PATCH] more on coding standard --- docs/code_style.md | 251 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 224 insertions(+), 27 deletions(-) diff --git a/docs/code_style.md b/docs/code_style.md index 219502b..a336034 100644 --- a/docs/code_style.md +++ b/docs/code_style.md @@ -16,13 +16,7 @@ PHP file formatting ### Indentation -All major PHP frameworks and libraries are using spaces. Common number is four: - -- Symfony 2: four spaces -- Zend Framework 1: four spaces -- Zend Framework 2: four spaces -- Pear: four spaces - +All code must be indented with tabs. That includes both PHP and JavaScript code. ### Maximum Line Length @@ -31,34 +25,123 @@ where possible. ### Line Termination +### Strings +- If string doesn't contain variables or single quotes, use single quotes. -### Brackets +~~~ +$str = 'Like this.'; +~~~ -It's better to be consistent with brackets not to remember where should we use -newline and where not: +- If string contains single quotes you can use double quotes to avoid extra escaping. +- You can use the following forms of variable substitution: ~~~ -class MyClass +$str1 = "Hello $username!"; +$str2 = "Hello {$username}!"; +~~~ + +The following is not permitted: + +~~~ +$str3 = "Hello ${username}!"; +~~~ + +### String concatenation + +When concatenating strings format it like the following: + +~~~ +$name = 'Yii' . ' ' . 'Framework'; +~~~ + +When string is long format is the following: + +~~~ +$sql = "SELECT *" + . "FROM `post` " + . "WHERE `id` = 121 "; +~~~ + + +### Numerically indexed arrays + +- Do not use negative numbers as array indexes. + +Use the following formatting when declaring array: + +~~~ +$arr = array(3, 14, 15, 'Yii', 'Framework'); +~~~ + +If there are too many elements for a single line: + +~~~ +$arr = array( + 3, 14, 15, + 92, 6, $test, + 'Yii', 'Framework', +); +~~~ + +### Associative arrays + +Use the following format for associative arrays: + +~~~ +$config = array( + 'name' => 'Yii', + 'options' => array( + 'usePHP' => true, + ), +); +~~~ + +### Classes + +- Classes should be named using `CamelCase`. +- The brace should always be written on the line underneath the class name. +- Every class must have a documentation block that conforms to the PHPDoc. +- All code in a class must be indented with a signle tab. +- Only one class is permitted per PHP file. +- When declaring public class members specify `public` keyword explicitly. +- Variables should be declared at the top of the class before any method declarations. +- Private variables should be named like `$_varName`. + +~~~ +/** + * Documentation + */ +class MyClass extends \yii\Object implements MyInterface { - public function myClassMethod() - { - if($x) { - // do it - } else { - // some code - } - } + // code } ~~~ -Use brackets even for one line `if`s. +### Functions and methods + +- Functions and methods should be named using `camelCase` with first letter lowercase. +- Class methods should always declare visibility using `private`, `protected` and + `public` modifiers. -> I chose to use the style as shown in Component.php because I want to make the -> curly brackets consistent with array brackets regarding newlines. Similar coding -> style is also used in Symfony 2. +~~~ +/** + * Documentation + */ +class Foo +{ + /** + * Documentation + */ + public function bar() + { + // code + return $value; + } +} +~~~ -### Use type hinting like +Use type hinting where possible: ~~~ public function __construct(CDbConnection $connection) @@ -67,12 +150,124 @@ public function __construct(CDbConnection $connection) } ~~~ -instead of +### Function and method calls + +~~~ +doIt(2, 3); + +doIt(array( + 'a' => 'b', +)); + +doIt('a', array( + 'a' => 'b', +)); +~~~ + +### Control statements + +- Control statement condition must have single space before and after parenthesis. +- Operators inside of parenthesis should be separated by spaces. +- Opening brace is on the same line. +- Closing brace is on a new line. +- Always use braces for single line staements. + +~~~ +if ($event === null) { + return new Event($this); +} elseif ($event instanceof CoolEvent) { + return $event->instance(); +} else { + return null; +} + +// the following is NOT allowed: +if(!$model) + throw new Exception('test'); +~~~ + + +### Switch + +Use the following formatting for switch: ~~~ -public function __construct($connection) +switch ($this->phpType) { + case 'string': + $a = (string)$value; + break; + case 'integer': + $a = (integer)$value; + break; + case 'boolean': + $a = (boolean)$value; + break; + default: + $a = null; + break; +} +~~~ + +Do not omit `break`. + +### Code documentation + +- Refer ot [phpDoc](http://phpdoc.org/) for documentation syntax. +- Code without any documentation is not allowed. +- All class files must contain a "file-level" docblock at the top of each file + and a "class-level" docblock immediately above each class. + +#### File + +~~~ + + * @since 2.0 + */ +class Component extends \yii\base\Object +~~~ + + +#### Function / method + +~~~ +/** + * Returns the list of attached event handlers for an event. + * You may manipulate the returned [[Vector]] object by adding or removing handlers. + * For example, + * + * ~~~ + * $component->getEventHandlers($eventName)->insertAt(0, $eventHandler); + * ~~~ + * + * @param string $name the event name + * @return Vector list of attached event handlers for the event + * @throws Exception if the event is not defined + */ +public function getEventHandlers($name) { - $this->connection = $connection; + if (!isset($this->_e[$name])) { + $this->_e[$name] = new Vector; + } + $this->ensureBehaviors(); + return $this->_e[$name]; } ~~~ @@ -86,6 +281,8 @@ libraries and frameworks. That's not only about PHP but about JavaScript as well. Since we're using jQuery a lot it's better to be consistent with its style as well. +Application style consistency is much more important than consistency with other frameworks and libraries. + - [Symfony 2](http://symfony.com/doc/current/contributing/code/standards.html) - [Zend Framework 1](http://framework.zend.com/manual/en/coding-standard.coding-style.html) - [Zend Framework 2](http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards)