more on coding standard

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:
+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
 
@@ -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
+- 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)
@@ -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)