Browse Source

more on coding standard

tags/2.0.0-beta
Alexander Makarov 13 years ago
parent
commit
251f6446d1
  1. 251
      docs/code_style.md

251
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.
~~~
$str = 'Like this.';
~~~
- If string contains single quotes you can use double quotes to avoid extra escaping.
- You can use the following forms of variable substitution:
~~~
$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
### Brackets
- Do not use negative numbers as array indexes.
It's better to be consistent with brackets not to remember where should we use
newline and where not:
Use the following formatting when declaring array:
~~~
class MyClass
$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
> 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.
- Functions and methods should be named using `camelCase` with first letter lowercase.
- Class methods should always declare visibility using `private`, `protected` and
`public` modifiers.
### Use type hinting like
~~~
/**
* Documentation
*/
class Foo
{
/**
* Documentation
*/
public function bar()
{
// code
return $value;
}
}
~~~
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
~~~
<?php
/**
* Component class file.
*
* @link http://www.yiiframework.com/
* @copyright Copyright &copy; 2008-2012 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
~~~
#### Class
~~~
/**
* Component is the base class that provides the *property*, *event* and *behavior* features.
*
* @include @yii/base/Component.md
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @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)

Loading…
Cancel
Save