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 ### Indentation
All major PHP frameworks and libraries are using spaces. Common number is four: All code must be indented with tabs. That includes both PHP and JavaScript code.
- Symfony 2: four spaces
- Zend Framework 1: four spaces
- Zend Framework 2: four spaces
- Pear: four spaces
### Maximum Line Length ### Maximum Line Length
@ -31,34 +25,123 @@ where possible.
### Line Termination ### 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 - If string contains single quotes you can use double quotes to avoid extra escaping.
newline and where not: - 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() // code
{
if($x) {
// do it
} else {
// some 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) 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 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. 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) - [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 1](http://framework.zend.com/manual/en/coding-standard.coding-style.html)
- [Zend Framework 2](http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards) - [Zend Framework 2](http://framework.zend.com/wiki/display/ZFDEV2/Coding+Standards)

Loading…
Cancel
Save