Browse files

doctrine1-documentation-28: Edit coding-standards.rst

  • Loading branch information...
1 parent 4ebb0ba commit 106bf7a76830de4944f127b67116f393e3009021 @jeserkin jeserkin committed Apr 25, 2012
Showing with 212 additions and 84 deletions.
  1. +212 −84 source/en/manual/coding-standards.rst
View
296 source/en/manual/coding-standards.rst
@@ -19,7 +19,7 @@ trailing whitespace from being accidentally injected into the output.
.. note::
Inclusion of arbitrary binary data as permitted by
- ``\_\_HALT_COMPILER()`` is prohibited from any Doctrine framework
+ ``__HALT_COMPILER()`` is prohibited from any Doctrine framework
PHP file or files derived from them. Use of this feature is only
permitted for special installation scripts.
@@ -68,12 +68,12 @@ Class names may only contain alphanumeric characters. Numbers are
permitted in class names but are discouraged. Underscores are only
permitted in place of the path separator, eg. the filename
"Doctrine/Table/Exception.php" must map to the class name
-"``Doctrine\_Table_Exception``".
+":php:class:`Doctrine_Table_Exception`".
If a class name is comprised of more than one word, the first letter of
each new word must be capitalized. Successive capitalized letters are
not allowed, e.g. a class "XML\_Reader" is not allowed while
-"Xml\_Reader" is acceptable.
+"Xml_Reader" is acceptable.
----------
Interfaces
@@ -83,13 +83,13 @@ Interface classes must follow the same conventions as other classes (see
above).
They must also end with the word "Interface" (unless the interface is
-approved not to contain it such as ``Doctrine_Overloadable``). Some
+approved not to contain it such as :php:class:`Doctrine_Overloadable`). Some
examples:
**Examples**
-- ``Doctrine\_Adapter_Interface``
-- ``Doctrine\_EventListener_Interface``
+- :php:class:`Doctrine_Adapter_Interface`
+- :php:class:`Doctrine_EventListener_Interface`
---------
Filenames
@@ -122,9 +122,9 @@ understandability of code.
For object-oriented programming, accessors for objects should always be
prefixed with either "get" or "set". This applies to all classes except
-for ``Doctrine_Record`` which has some accessor methods prefixed with
+for :php:class:`Doctrine_Record` which has some accessor methods prefixed with
'obtain' and 'assign'. The reason for this is that since all user
-defined ActiveRecords inherit ``Doctrine_Record``, it should populate
+defined ActiveRecords inherit :php:class:`Doctrine_Record`, it should populate
the get / set namespace as little as possible.
.. note::
@@ -142,16 +142,20 @@ not permitted. Numbers are permitted in variable names but are
discouraged. They must always start with a lowercase letter and follow
the "camelCaps" capitalization convention. Verbosity is encouraged.
Variables should always be as verbose as practical. Terse variable names
-such as ":code:`i" and "`\ n" are discouraged for anything other than
+such as "$i" and "$n" are discouraged for anything other than
the smallest loop contexts. If a loop contains more than 20 lines of
code, the variables for the indices need to have more descriptive names.
Within the framework certain generic object variables should always use
the following names:
-\|\|~ Object type \|\|~ Variable name \|\| \|\| ``Doctrine_Connection``
-\|\| $conn \|\| \|\| ``Doctrine_Collection`` \|\| $coll \|\| \|\|
-``Doctrine\_Manager`` \|\| $manager \|\| \|\| ``Doctrine_Query`` \|\|
-$q \|\|
+======================= ==================
+Object type Variable name
+======================= ==================
+``Doctrine_Connection`` $conn
+``Doctrine_Collection`` $coll
+``Doctrine_Manager`` $manager
+``Doctrine_Query`` $q
+======================= ==================
There are cases when more descriptive names are more appropriate (for
example when multiple objects of the same class are used in same
@@ -165,31 +169,50 @@ Constants
Constants may contain both alphanumeric characters and the underscore.
They must always have all letters capitalized. For readablity reasons,
words in constant names must be separated by underscore characters. For
-example, ``ATTR\_EXC\_LOGGING`` is permitted but ``ATTR_EXCLOGGING`` is
+example, ``ATTR_EXC_LOGGING`` is permitted but ``ATTR_EXCLOGGING`` is
not.Constants must be defined as class members by using the "const"
construct. Defining constants in the global scope with "define" is NOT
permitted.
- class Doctrine\_SomeClass { const MY\_CONSTANT = 'something'; }
+::
-echo $Doctrine\_SomeClass::MY\_CONSTANT;
+ class Doctrine_SomeClass
+ {
+ const MY_CONSTANT = 'something';
+ }
+
+ echo $Doctrine_SomeClass::MY_CONSTANT;
--------------
Record Columns
--------------
-All record columns must be in lowercase and usage of underscores(\_) are
+All record columns must be in lowercase and usage of underscores(_) are
encouraged for columns that consist of more than one word.
- class User { public function setTableDefinition() {
-$this->hasColumn('home\_address', 'string'); } }
+::
-Foreign key fields must be in format ``[table\_name]_[column]``. The
+ class User
+ {
+ public function setTableDefinition()
+ {
+ $this->hasColumn( 'home_address', 'string' );
+ }
+ }
+
+Foreign key fields must be in format ``[table_name]_[column]``. The
next example is a field that is a foreign key that points to
``user(id)``:
- class Phonenumber extends Doctrine\_Record { public function
-setTableDefinition() { $this->hasColumn('user\_id', 'integer'); } }
+::
+
+ class Phonenumber extends Doctrine_Record
+ {
+ public function setTableDefinition()
+ {
+ $this->hasColumn( 'user_id', 'integer' );
+ }
+ }
============
Coding Style
@@ -210,41 +233,57 @@ Strings
When a string is literal (contains no variable substitutions), the
apostrophe or "single quote" must always used to demarcate the string:
-++++ Literal String
+Literal String
+++++++++++++++
+
+::
- $string = 'something';
+ $string = 'something';
When a literal string itself contains apostrophes, it is permitted to
demarcate the string with quotation marks or "double quotes". This is
especially encouraged for SQL statements:
-++++ String Containing Apostrophes
+String Containing Apostrophes
++++++++++++++++++++++++++++++
- $sql = "SELECT id, name FROM people WHERE name = 'Fred' OR name =
-'Susan'";
+::
+
+ $sql = "SELECT id, name FROM people WHERE name = 'Fred' OR name = 'Susan'";
-++++ Variable Substitution
+Variable Substitution
++++++++++++++++++++++
Variable substitution is permitted using the following form:
- // variable substitution $greeting = "Hello $name, welcome back!";
+::
+
+ // variable substitution
+ $greeting = "Hello $name, welcome back!";
-++++ String Concatenation
+String Concatenation
+++++++++++++++++++++
Strings may be concatenated using the "." operator. A space must always
be added before and after the "." operator to improve readability:
- $framework = 'Doctrine' . ' ORM ' . 'Framework';
+::
+
+ $framework = 'Doctrine' . ' ORM ' . 'Framework';
-++++ Concatenation Line Breaking
+Concatenation Line Breaking
++++++++++++++++++++++++++++
When concatenating strings with the "." operator, it is permitted to
break the statement into multiple lines to improve readability. In these
cases, each successive line should be padded with whitespace such that
the "."; operator is aligned under the "=" operator:
- $sql = "SELECT id, name FROM user " . "WHERE name = ? " . "ORDER BY
-name ASC";
+::
+
+ $sql = "SELECT id, name FROM user "
+ . "WHERE name = ? "
+ . "ORDER BY name ASC";
------
Arrays
@@ -262,13 +301,18 @@ the statement into multiple lines. In this case, each successive line
must be padded with whitespace such that both the keys and the values
are aligned:
- $sampleArray = array('Doctrine', 'ORM', 1, 2, 3);
+::
-$sampleArray = array(1, 2, 3, $a, $b, $c,
- 56.44, $d, 500);
+ $sampleArray = array( 'Doctrine', 'ORM', 1, 2, 3 );
-$sampleArray = array('first' => 'firstValue', 'second' =>
-'secondValue');
+ $sampleArray = array( 1, 2, 3,
+ $a, $b, $c,
+ 56.44, $d, 500 );
+
+ $sampleArray = array(
+ 'first' => 'firstValue',
+ 'second' => 'secondValue'
+ );
-------
Classes
@@ -283,8 +327,16 @@ additional code in a class file is NOT permitted.
This is an example of an acceptable class declaration:
- /\*\* \* Documentation here \*/ class Doctrine\_SampleClass { // entire
-content of class // must be indented four spaces }
+::
+
+ /**
+ * Documentation here
+ */
+ class Doctrine_SampleClass
+ {
+ // entire content of class
+ // must be indented four spaces
+ }
---------------------
Functions and Methods
@@ -298,66 +350,99 @@ and the opening parenthesis for the arguments. Functions in the global
scope are strongly discouraged. This is an example of an acceptable
function declaration in a class:
- /\*\* \* Documentation Block Here */ class Foo { /*\* \* Documentation
-Block Here \*/ public function bar() { // entire content of function //
-must be indented four spaces }
-
::
- public function bar2()
+ /**
+ * Documentation Block Here
+ */
+ class Foo
{
-
+ /**
+ * Documentation Block Here
+ */
+ public function bar()
+ {
+ // entire content of function
+ // must be indented four spaces
+ }
+
+ public function bar2()
+ {
+
+ }
}
-}
-
.. note::
Functions must be separated by only ONE single new line
like is done above between the ``bar()`` and ``bar2()`` methods.
Passing by-reference is permitted in the function declaration only:
- /\*\* \* Documentation Block Here */ class Foo { /*\* \* Documentation
-Block Here \*/ public function bar(&$baz) { } }
+::
+
+ /**
+ * Documentation Block Here
+ */
+ class Foo
+ {
+ /**
+ * Documentation Block Here
+ */
+ public function bar( &$baz )
+ {
+
+ }
+ }
Call-time pass by-reference is prohibited. The return value must not be
enclosed in parentheses. This can hinder readability and can also break
code if a method is later changed to return by reference.
- /\*\* \* Documentation Block Here */ class Foo { /*\*
- \* WRONG
- \*/
- public function bar() { return($this->bar); }
-
::
- /**
- * RIGHT
- */
- public function bar()
+ /**
+ * Documentation Block Here
+ */
+ class Foo
{
- return $this->bar;
+ /**
+ * WRONG
+ */
+ public function bar()
+ {
+ return( $this->bar );
+ }
+
+ /**
+ * RIGHT
+ */
+ public function bar()
+ {
+ return $this->bar;
+ }
}
-}
-
Function arguments are separated by a single trailing space after the
comma delimiter. This is an example of an acceptable function call for a
function that takes three arguments:
- threeArguments(1, 2, 3);
+::
+
+ threeArguments( 1, 2, 3 );
Call-time pass by-reference is prohibited. See above for the proper way
to pass function arguments by-reference. For functions whose arguments
permitted arrays, the function call may include the array construct and
can be split into multiple lines to improve readability. In these cases,
the standards for writing arrays still apply:
- threeArguments(array(1, 2, 3), 2, 3);
+::
+
+ threeArguments( array( 1, 2, 3 ), 2, 3 );
-threeArguments(array(1, 2, 3, 'Framework', 'Doctrine', 56.44, 500), 2,
-3);
+ threeArguments( array( 1, 2, 3, 'Framework',
+ 'Doctrine', 56.44, 500 ), 2, 3 );
------------------
Control Statements
@@ -373,23 +458,48 @@ the same line as the conditional statement. The closing brace is always
written on its own line. Any content within the braces must be indented
four spaces.
- if ($foo != 2) { $foo = 2; }
+::
+
+ if ( $foo != 2 )
+ {
+ $foo = 2;
+ }
For if statements that include elseif or else, the formatting must be as
in these examples:
- if ($foo != 1) { $foo = 1; } else {
- $foo = 3; }
+::
-if ($foo != 2) { :code:`foo = 2; } elseif (`\ foo == 1) { $foo = 3; }
-else {
- $foo = 11; }
+ if ( $foo != 1 )
+ {
+ $foo = 1;
+ }
+ else
+ {
+ $foo = 3;
+ }
+
+ if ( $foo != 2 )
+ {
+ $foo = 2;
+ }
+ elseif ( $foo == 1 )
+ {
+ $foo = 3;
+ }
+ else
+ {
+ $foo = 11;
+ }
When ! operand is being used it must use the following formatting:
- if ( ! $foo) {
+::
+
+ if ( ! $foo )
+ {
-}
+ }
Control statements written with the switch construct must have a single
space before the opening parenthesis of the conditional statement, and
@@ -398,8 +508,18 @@ the switch statement must be indented four spaces. Content under each
case statement must be indented an additional four spaces but the breaks
must be at the same indentation level as the case statements.
- switch ($case) { case 1: case 2: break; case 3: break; default: break;
-}
+::
+
+ switch ( $case )
+ {
+ case 1:
+ case 2:
+ break;
+ case 3:
+ break;
+ default:
+ break;
+ }
The construct default may never be omitted from a switch statement.
@@ -411,7 +531,7 @@ Documentation Format:
All documentation blocks ("docblocks") must be compatible with the
phpDocumentor format. Describing the phpDocumentor format is beyond the
-scope of this document. For more information, visit: http://phpdoc.org/
+scope of this document. For more information, visit: `http://phpdoc.org/ <http://phpdoc.org/>`
Every method, must have a docblock that contains at a minimum:
@@ -424,19 +544,27 @@ Every method, must have a docblock that contains at a minimum:
If a function/method may throw an exception, use @throws:
- /\* \* Test function \* \* @throws Doctrine\_Exception \*/ public
-function test() { throw new Doctrine\_Exception('This function did not
-work'); }
+::
+
+ /*
+ * Test function
+ *
+ * @throws Doctrine_Exception
+ */
+ public function test()
+ {
+ throw new Doctrine_Exception('This function did not work');
+ }
==========
Conclusion
==========
-This is the last chapter of //Doctrine ORM for PHP - Guide to Doctrine
-for PHP//. I really hope that this book was a useful piece of
+This is the last chapter of **Doctrine ORM for PHP - Guide to Doctrine
+for PHP**. I really hope that this book was a useful piece of
documentation and that you are now comfortable with using Doctrine and
will be able to come back to easily reference things as needed.
As always, follow the Doctrine :)
-Thanks, Jon
+Thanks, Jon

0 comments on commit 106bf7a

Please sign in to comment.