|
|
@@ -9,16 +9,18 @@
|
|
|
<title>Scope</title>
|
|
|
|
|
|
<para>
|
|
|
- This document provides guidelines for code formatting and documentation to individuals
|
|
|
- and teams contributing to Zend Framework. Many developers using Zend Framework have also
|
|
|
- found these coding standards useful because their code's style remains consistent with all
|
|
|
- Zend Framework code. It is also worth noting that it requires significant effort to fully
|
|
|
- specify coding standards.
|
|
|
+ This document provides guidelines for code formatting and documentation to
|
|
|
+ individuals and teams contributing to Zend Framework. Many developers using Zend
|
|
|
+ Framework have also found these coding standards useful because their code's style
|
|
|
+ remains consistent with all Zend Framework code. It is also worth noting that it
|
|
|
+ requires significant effort to fully specify coding standards.
|
|
|
|
|
|
- Note: Sometimes developers consider the establishment of a standard more important than what that
|
|
|
- standard actually suggests at the most detailed level of design. The guidelines in the Zend Framework
|
|
|
- coding standards capture practices that have worked well on the ZF project. You may modify these standards
|
|
|
- or use them as is in accordance with the terms of our <ulink url="http://framework.zend.com/license">license</ulink>
|
|
|
+ Note: Sometimes developers consider the establishment of a standard more important
|
|
|
+ than what that standard actually suggests at the most detailed level of design. The
|
|
|
+ guidelines in the Zend Framework coding standards capture practices that have worked
|
|
|
+ well on the ZF project. You may modify these standards or use them as is in
|
|
|
+ accordance with the terms of our
|
|
|
+ <ulink url="http://framework.zend.com/license">license</ulink>
|
|
|
</para>
|
|
|
<para>
|
|
|
Topics covered in the ZF coding standards include:
|
|
|
@@ -47,9 +49,10 @@
|
|
|
<title>Goals</title>
|
|
|
|
|
|
<para>
|
|
|
- Coding standards are important in any development project, but they are particularly important
|
|
|
- when many developers are working on the same project. Coding standards
|
|
|
- help ensure that the code is high quality, has fewer bugs, and can be easily maintained.
|
|
|
+ Coding standards are important in any development project, but they are particularly
|
|
|
+ important when many developers are working on the same project. Coding standards
|
|
|
+ help ensure that the code is high quality, has fewer bugs, and can be easily
|
|
|
+ maintained.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
</sect1>
|
|
|
@@ -61,14 +64,16 @@
|
|
|
<title>General</title>
|
|
|
|
|
|
<para>
|
|
|
- For files that contain only PHP code, the closing tag ("?>") is never permitted. It is
|
|
|
- not required by PHP, and omitting it prevents the accidental injection of trailing white space into the response.
|
|
|
+ For files that contain only PHP code, the closing tag ("?>") is never permitted. It
|
|
|
+ is not required by PHP, and omitting it prevents the accidental injection of
|
|
|
+ trailing white space into the response.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- <emphasis>IMPORTANT:</emphasis> Inclusion of arbitrary binary data as permitted by <code>__HALT_COMPILER()</code>
|
|
|
- is prohibited from PHP files in the Zend Framework project or files derived from them. Use of
|
|
|
- this feature is only permitted for some installation scripts.
|
|
|
+ <emphasis>IMPORTANT:</emphasis> Inclusion of arbitrary binary data as permitted by
|
|
|
+ <code>__HALT_COMPILER()</code> is prohibited from PHP files in the Zend Framework
|
|
|
+ project or files derived from them. Use of this feature is only permitted for some
|
|
|
+ installation scripts.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
@@ -82,9 +87,10 @@
|
|
|
<title>Maximum Line Length</title>
|
|
|
|
|
|
<para>
|
|
|
- The target line length is 80 characters. That is to say, ZF developers should strive keep each line of their code
|
|
|
- under 80 characters where possible and practical. However, longer lines are
|
|
|
- acceptable in some circumstances. The maximum length of any line of PHP code is 120 characters.
|
|
|
+ The target line length is 80 characters. That is to say, ZF developers should strive
|
|
|
+ keep each line of their code under 80 characters where possible and practical.
|
|
|
+ However, longer lines are acceptable in some circumstances. The maximum length of
|
|
|
+ any line of PHP code is 120 characters.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
@@ -92,13 +98,15 @@
|
|
|
<title>Line Termination</title>
|
|
|
|
|
|
<para>
|
|
|
- Line termination follows the Unix text file convention. Lines must end
|
|
|
- with a single linefeed (LF) character. Linefeed characters are represented as ordinal 10, or hexadecimal 0x0A.
|
|
|
+ Line termination follows the Unix text file convention. Lines must end with a
|
|
|
+ single linefeed (LF) character. Linefeed characters are represented as ordinal 10,
|
|
|
+ or hexadecimal 0x0A.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Note: Do not use carriage returns (CR) as is the convention in Apple OS's (0x0D) or the carriage
|
|
|
- return/linefeed combination (CRLF) as is standard for the Windows OS (0x0D, 0x0A).
|
|
|
+ Note: Do not use carriage returns (CR) as is the convention in Apple OS's (0x0D) or
|
|
|
+ the carriage return/linefeed combination (CRLF) as is standard for the Windows OS
|
|
|
+ (0x0D, 0x0A).
|
|
|
</para>
|
|
|
</sect2>
|
|
|
</sect1>
|
|
|
@@ -110,17 +118,17 @@
|
|
|
<title>Classes</title>
|
|
|
|
|
|
<para>
|
|
|
- Zend Framework standardizes on a class naming convention whereby the names
|
|
|
- of the classes directly map to the directories in which they are stored.
|
|
|
- The root level directory of the ZF standard library is the "Zend/" directory, whereas
|
|
|
+ Zend Framework standardizes on a class naming convention whereby the names of the
|
|
|
+ classes directly map to the directories in which they are stored. The root level
|
|
|
+ directory of the ZF standard library is the "Zend/" directory, whereas
|
|
|
the root level directory of the ZF extras library is the "ZendX/" directory. All
|
|
|
Zend Framework classes are stored hierarchically under these root directories..
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
Class names may only contain alphanumeric characters. Numbers are permitted
|
|
|
- in class names but are discouraged in most cases. Underscores are only permitted in place
|
|
|
- of the path separator; the filename "Zend/Db/Table.php" must map to the
|
|
|
+ in class names but are discouraged in most cases. Underscores are only permitted in
|
|
|
+ place of the path separator; the filename "Zend/Db/Table.php" must map to the
|
|
|
class name "Zend_Db_Table".
|
|
|
</para>
|
|
|
|
|
|
@@ -131,16 +139,17 @@
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- These conventions define a pseudo-namespace mechanism for Zend Framework. Zend Framework
|
|
|
- will adopt the PHP namespace feature when it becomes available and is feasible for our developers to use in their applications.
|
|
|
+ These conventions define a pseudo-namespace mechanism for Zend Framework. Zend
|
|
|
+ Framework will adopt the PHP namespace feature when it becomes available and is
|
|
|
+ feasible for our developers to use in their applications.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- See the class names in the standard and extras libraries for examples of this classname convention.
|
|
|
-
|
|
|
- <emphasis>IMPORTANT:</emphasis> Code that must be deployed alongside ZF libraries but is not
|
|
|
- part of the standard or extras libraries (e.g. application code or libraries that are not distributed by Zend)
|
|
|
- must never start with "Zend_" or "ZendX_".
|
|
|
+ See the class names in the standard and extras libraries for examples of this
|
|
|
+ classname convention. <emphasis>IMPORTANT:</emphasis> Code that must be deployed
|
|
|
+ alongside ZF libraries but is not part of the standard or extras libraries (e.g.
|
|
|
+ application code or libraries that are not distributed by Zend) must never start
|
|
|
+ with "Zend_" or "ZendX_".
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
@@ -153,9 +162,9 @@
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Any file that contains PHP code should end with the extension ".php", with the notable exception of view scripts. The following
|
|
|
- examples show acceptable filenames for Zend Framework classes:
|
|
|
-
|
|
|
+ Any file that contains PHP code should end with the extension ".php", with the
|
|
|
+ notable exception of view scripts. The following examples show acceptable filenames
|
|
|
+ for Zend Framework classes:
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
Zend/Db.php
|
|
|
|
|
|
@@ -172,18 +181,20 @@ Zend/View/Helper/FormRadio.php
|
|
|
<title>Functions and Methods</title>
|
|
|
|
|
|
<para>
|
|
|
- Function names may only contain alphanumeric characters. Underscores are not permitted.
|
|
|
- Numbers are permitted in function names but are discouraged in most cases.
|
|
|
+ Function names may only contain alphanumeric characters. Underscores are not
|
|
|
+ permitted. Numbers are permitted in function names but are discouraged in most
|
|
|
+ cases.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Function names must always start with a lowercase letter. When a function name consists
|
|
|
- of more than one word, the first letter of each new word must be capitalized. This is
|
|
|
- commonly called "camelCase" formatting.
|
|
|
+ Function names must always start with a lowercase letter. When a function name
|
|
|
+ consists of more than one word, the first letter of each new word must be
|
|
|
+ capitalized. This is commonly called "camelCase" formatting.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Verbosity is generally encouraged. Function names should be as verbose as is practical to fully describe their purpose and behavior.
|
|
|
+ Verbosity is generally encouraged. Function names should be as verbose as is
|
|
|
+ practical to fully describe their purpose and behavior.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
@@ -199,9 +210,10 @@ widgetFactory()
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- For object-oriented programming, accessors for instance or static variables should always be prefixed with
|
|
|
- "get" or "set". In implementing design patterns, such as the singleton or factory
|
|
|
- patterns, the name of the method should contain the pattern name where practical to more thoroughly describe behavior.
|
|
|
+ For object-oriented programming, accessors for instance or static variables should
|
|
|
+ always be prefixed with "get" or "set". In implementing design patterns, such as the
|
|
|
+ singleton or factory patterns, the name of the method should contain the pattern
|
|
|
+ name where practical to more thoroughly describe behavior.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
@@ -212,8 +224,8 @@ widgetFactory()
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Functions in the global scope (a.k.a "floating functions") are permitted but discouraged in most cases.
|
|
|
- Consider wrapping these functions in a static class.
|
|
|
+ Functions in the global scope (a.k.a "floating functions") are permitted but
|
|
|
+ discouraged in most cases. Consider wrapping these functions in a static class.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
@@ -221,15 +233,16 @@ widgetFactory()
|
|
|
<title>Variables</title>
|
|
|
|
|
|
<para>
|
|
|
- Variable names may only contain alphanumeric characters. Underscores are not permitted.
|
|
|
- Numbers are permitted in variable names but are discouraged in most cases.
|
|
|
+ Variable names may only contain alphanumeric characters. Underscores are not
|
|
|
+ permitted. Numbers are permitted in variable names but are discouraged in most
|
|
|
+ cases.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
For instance variables that are declared with the "private" or "protected" modifier,
|
|
|
- the first character of the variable name must be a single underscore. This is the only
|
|
|
- acceptable application of an underscore in a variable name. Member variables declared "public"
|
|
|
- should never start with an underscore.
|
|
|
+ the first character of the variable name must be a single underscore. This is the
|
|
|
+ only acceptable application of an underscore in a variable name. Member variables
|
|
|
+ declared "public" should never start with an underscore.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
@@ -238,9 +251,11 @@ widgetFactory()
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Verbosity is generally encouraged. Variables should always be as verbose as practical to describe the data that the developer
|
|
|
- intends to store in them. Terse variable names such as "$i" and "$n" are discouraged for all but the smallest loop contexts.
|
|
|
- If a loop contains more than 20 lines of code, the index variables should have more descriptive names.
|
|
|
+ Verbosity is generally encouraged. Variables should always be as verbose as
|
|
|
+ practical to describe the data that the developer intends to store in them. Terse
|
|
|
+ variable names such as "$i" and "$n" are discouraged for all but the smallest loop
|
|
|
+ contexts. If a loop contains more than 20 lines of code, the index variables should
|
|
|
+ have more descriptive names.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
@@ -248,12 +263,13 @@ widgetFactory()
|
|
|
<title>Constants</title>
|
|
|
|
|
|
<para>
|
|
|
- Constants may contain both alphanumeric characters and underscores. Numbers are permitted
|
|
|
- in constant names.
|
|
|
+ Constants may contain both alphanumeric characters and underscores. Numbers are
|
|
|
+ permitted in constant names.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- All letters used in a constant name must be capitalized, while all words in a constant name must be separated by underscore characters.
|
|
|
+ All letters used in a constant name must be capitalized, while all words in a
|
|
|
+ constant name must be separated by underscore characters.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
@@ -262,8 +278,9 @@ widgetFactory()
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Constants must be defined as class members with the "const" modifier. Defining constants
|
|
|
- in the global scope with the "define" function is permitted but strongly discouraged.
|
|
|
+ Constants must be defined as class members with the "const" modifier. Defining
|
|
|
+ constants in the global scope with the "define" function is permitted but strongly
|
|
|
+ discouraged.
|
|
|
</para>
|
|
|
</sect2>
|
|
|
</sect1>
|
|
|
@@ -285,8 +302,9 @@ widgetFactory()
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Short tags are never allowed. For files containing only PHP code, the
|
|
|
- closing tag must always be omitted (See <xref linkend="coding-standard.php-file-formatting.general" />).
|
|
|
+ Short tags are never allowed. For files containing only PHP code, the closing tag
|
|
|
+ must always be omitted (See <xref
|
|
|
+ linkend="coding-standard.php-file-formatting.general" />).
|
|
|
</para>
|
|
|
</sect2>
|
|
|
|
|
|
@@ -386,8 +404,8 @@ $sql = "SELECT `id`, `name` FROM `people` "
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- When declaring indexed arrays with the <code>array</code> function, a trailing space must be
|
|
|
- added after each comma delimiter to improve readability:
|
|
|
+ When declaring indexed arrays with the <code>array</code> function, a trailing
|
|
|
+ space must be added after each comma delimiter to improve readability:
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
|
|
|
@@ -395,9 +413,9 @@ $sampleArray = array(1, 2, 3, 'Zend', 'Studio');
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- It is permitted to declare multi-line indexed arrays using the "array" construct.
|
|
|
- In this case, each successive line must be padded with spaces such that beginning of
|
|
|
- each line is aligned:
|
|
|
+ It is permitted to declare multi-line indexed arrays using the "array"
|
|
|
+ construct. In this case, each successive line must be padded with spaces such
|
|
|
+ that beginning of each line is aligned:
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
|
|
|
@@ -411,9 +429,10 @@ $sampleArray = array(1, 2, 3, 'Zend', 'Studio',
|
|
|
<title>Associative Arrays</title>
|
|
|
|
|
|
<para>
|
|
|
- When declaring associative arrays with the <code>array</code> construct, breaking the statement into multiple lines
|
|
|
- is encouraged. In this case, each successive line must be padded with white space such that both the keys and the values are aligned:
|
|
|
-
|
|
|
+ When declaring associative arrays with the <code>array</code> construct,
|
|
|
+ breaking the statement into multiple lines is encouraged. In this case, each
|
|
|
+ successive line must be padded with white space such that both the keys and the
|
|
|
+ values are aligned:
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
$sampleArray = array('firstKey' => 'firstValue',
|
|
|
'secondKey' => 'secondValue');
|
|
|
@@ -433,14 +452,16 @@ $sampleArray = array('firstKey' => 'firstValue',
|
|
|
</para><para>
|
|
|
The brace should always be written on the line underneath the class name.
|
|
|
</para><para>
|
|
|
- Every class must have a documentation block that conforms to the PHPDocumentor standard.
|
|
|
+ Every class must have a documentation block that conforms to the PHPDocumentor
|
|
|
+ standard.
|
|
|
</para><para>
|
|
|
All code in a class must be indented with four spaces.
|
|
|
</para><para>
|
|
|
Only one class is permitted in each PHP file.
|
|
|
</para><para>
|
|
|
Placing additional code in class files is permitted but discouraged.
|
|
|
- In such files, two blank lines must separate the class from any additional PHP code in the class file.
|
|
|
+ In such files, two blank lines must separate the class from any additional PHP
|
|
|
+ code in the class file.
|
|
|
</para><para>
|
|
|
The following is an example of an acceptable class declaration:
|
|
|
|
|
|
@@ -461,17 +482,19 @@ class SampleClass
|
|
|
<title>Class Member Variables</title>
|
|
|
|
|
|
<para>
|
|
|
- Member variables must be named according to Zend Framework's variable naming conventions.
|
|
|
+ Member variables must be named according to Zend Framework's variable naming
|
|
|
+ conventions.
|
|
|
</para>
|
|
|
<para>
|
|
|
- Any variables declared in a class must be listed at the top of the class, above the
|
|
|
- declaration of any methods.
|
|
|
+ Any variables declared in a class must be listed at the top of the class, above
|
|
|
+ the declaration of any methods.
|
|
|
</para>
|
|
|
<para>
|
|
|
The <code>var</code> construct is not permitted. Member variables always declare
|
|
|
- their visibility by using one of the <code>private</code>, <code>protected</code>,
|
|
|
- or <code>public</code> modifiers. Giving access to member variables directly by declaring them
|
|
|
- as public is permitted but discouraged in favor of accessor methods (set/get).
|
|
|
+ their visibility by using one of the <code>private</code>,
|
|
|
+ <code>protected</code>, or <code>public</code> modifiers. Giving access to
|
|
|
+ member variables directly by declaring them as public is permitted but
|
|
|
+ discouraged in favor of accessor methods (set/get).
|
|
|
</para>
|
|
|
</sect3>
|
|
|
</sect2>
|
|
|
@@ -483,7 +506,8 @@ class SampleClass
|
|
|
<title>Function and Method Declaration</title>
|
|
|
|
|
|
<para>
|
|
|
- Functions must be named according to the Zend Framework function naming conventions.
|
|
|
+ Functions must be named according to the Zend Framework function naming
|
|
|
+ conventions.
|
|
|
</para>
|
|
|
<para>
|
|
|
Methods inside classes must always declare their visibility by using
|
|
|
@@ -492,9 +516,8 @@ class SampleClass
|
|
|
</para>
|
|
|
<para>
|
|
|
As with classes, the brace should always be written on the line underneath the
|
|
|
- function name.
|
|
|
-
|
|
|
- Space between the function name and the opening parenthesis for the arguments is not permitted.
|
|
|
+ function name. Space between the function name and the opening parenthesis for
|
|
|
+ the arguments is not permitted.
|
|
|
</para>
|
|
|
<para>
|
|
|
Functions in the global scope are strongly discouraged.
|
|
|
@@ -521,7 +544,8 @@ class Foo
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- <emphasis>NOTE:</emphasis> Pass-by-reference is the only parameter passing mechanism permitted in a method declaration.
|
|
|
+ <emphasis>NOTE:</emphasis> Pass-by-reference is the only parameter passing
|
|
|
+ mechanism permitted in a method declaration.
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
/**
|
|
|
@@ -543,8 +567,9 @@ class Foo
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- The return value must not be enclosed in parentheses. This can hinder readability, in additional to breaking code
|
|
|
- if a method is later changed to return by reference.
|
|
|
+ The return value must not be enclosed in parentheses. This can hinder
|
|
|
+ readability, in additional to breaking code if a method is later changed to
|
|
|
+ return by reference.
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
/**
|
|
|
@@ -577,8 +602,9 @@ class Foo
|
|
|
<title>Function and Method Usage</title>
|
|
|
|
|
|
<para>
|
|
|
- Function arguments should be separated by a single trailing space after the comma delimiter.
|
|
|
- The following is an example of an acceptable invocation of a function that takes three arguments:
|
|
|
+ Function arguments should be separated by a single trailing space after the
|
|
|
+ comma delimiter. The following is an example of an acceptable invocation of a
|
|
|
+ function that takes three arguments:
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
threeArguments(1, 2, 3);
|
|
|
@@ -586,8 +612,8 @@ threeArguments(1, 2, 3);
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Call-time pass-by-reference is strictly prohibited. See the function declarations section
|
|
|
- for the proper way to pass function arguments by-reference.
|
|
|
+ Call-time pass-by-reference is strictly prohibited. See the function
|
|
|
+ declarations section for the proper way to pass function arguments by-reference.
|
|
|
</para>
|
|
|
<para>
|
|
|
In passing arrays as arguments to a function, the function call may include the
|
|
|
@@ -613,20 +639,20 @@ threeArguments(array(1, 2, 3, 'Zend', 'Studio',
|
|
|
|
|
|
<para>
|
|
|
Control statements based on the <code>if</code> and <code>elseif</code>
|
|
|
- constructs must have a single space before the opening parenthesis of the conditional
|
|
|
- and a single space after the closing parenthesis.
|
|
|
+ constructs must have a single space before the opening parenthesis of the
|
|
|
+ conditional and a single space after the closing parenthesis.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Within the conditional statements between the parentheses, operators must be separated
|
|
|
- by spaces for readability. Inner parentheses are encouraged to improve logical grouping
|
|
|
- for larger conditional expressions.
|
|
|
+ Within the conditional statements between the parentheses, operators must be
|
|
|
+ separated by spaces for readability. Inner parentheses are encouraged to improve
|
|
|
+ logical grouping for larger conditional expressions.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- The opening brace is written on 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 using four spaces.
|
|
|
+ The opening brace is written on 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 using four spaces.
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
if ($a != 2) {
|
|
|
@@ -636,8 +662,9 @@ if ($a != 2) {
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- For "if" statements that include "elseif" or "else", the formatting conventions are similar to the "if" construct.
|
|
|
- The following examples demonstrate proper formatting for "if" statements with "else" and/or "elseif" constructs:
|
|
|
+ For "if" statements that include "elseif" or "else", the formatting conventions
|
|
|
+ are similar to the "if" construct. The following examples demonstrate proper
|
|
|
+ formatting for "if" statements with "else" and/or "elseif" constructs:
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
if ($a != 2) {
|
|
|
@@ -654,14 +681,14 @@ if ($a != 2) {
|
|
|
$a = 7;
|
|
|
}
|
|
|
]]></programlisting>
|
|
|
- PHP allows statements to be written without braces in some circumstances.
|
|
|
- This coding standard makes no differentiation- all "if", "elseif" or "else" statements
|
|
|
- must use braces.
|
|
|
+ PHP allows statements to be written without braces in some circumstances. This
|
|
|
+ coding standard makes no differentiation- all "if", "elseif" or "else"
|
|
|
+ statements must use braces.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- Use of the "elseif" construct is permitted but strongly discouraged in favor of the
|
|
|
- "else if" combination.
|
|
|
+ Use of the "elseif" construct is permitted but strongly discouraged in favor of
|
|
|
+ the "else if" combination.
|
|
|
</para>
|
|
|
</sect3>
|
|
|
|
|
|
@@ -669,13 +696,15 @@ if ($a != 2) {
|
|
|
<title>Switch</title>
|
|
|
|
|
|
<para>
|
|
|
- Control statements written with the "switch" statement must have a single space before
|
|
|
- the opening parenthesis of the conditional statement and after the closing parenthesis.
|
|
|
+ Control statements written with the "switch" statement must have a single space
|
|
|
+ before the opening parenthesis of the conditional statement and after the
|
|
|
+ closing parenthesis.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- All content within the "switch" statement must be indented using four spaces. Content under
|
|
|
- each "case" statement must be indented using an additional four spaces.
|
|
|
+ All content within the "switch" statement must be indented using four spaces.
|
|
|
+ Content under each "case" statement must be indented using an additional four
|
|
|
+ spaces.
|
|
|
</para>
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
@@ -692,14 +721,17 @@ switch ($numPeople) {
|
|
|
]]></programlisting>
|
|
|
|
|
|
<para>
|
|
|
- The construct <code>default</code> should never be omitted from a <code>switch</code> statement.
|
|
|
+ The construct <code>default</code> should never be omitted from a
|
|
|
+ <code>switch</code> statement.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- <emphasis>NOTE:</emphasis> It is sometimes useful to write a <code>case</code> statement which falls through
|
|
|
- to the next case by not including a <code>break</code> or <code>return</code> within that case. To distinguish
|
|
|
- these cases from bugs, any <code>case</code> statement where <code>break</code> or <code>return</code> are
|
|
|
- omitted should contain a comment indicating that the break was intentionally omitted.
|
|
|
+ <emphasis>NOTE:</emphasis> It is sometimes useful to write a <code>case</code>
|
|
|
+ statement which falls through to the next case by not including a
|
|
|
+ <code>break</code> or <code>return</code> within that case. To distinguish these
|
|
|
+ cases from bugs, any <code>case</code> statement where <code>break</code> or
|
|
|
+ <code>return</code> are omitted should contain a comment indicating that the
|
|
|
+ break was intentionally omitted.
|
|
|
</para>
|
|
|
</sect3>
|
|
|
</sect2>
|
|
|
@@ -711,14 +743,16 @@ switch ($numPeople) {
|
|
|
<title>Documentation Format</title>
|
|
|
|
|
|
<para>
|
|
|
- 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: <ulink url="http://phpdoc.org/">http://phpdoc.org/</ulink>
|
|
|
+ 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: <ulink
|
|
|
+ url="http://phpdoc.org/">http://phpdoc.org/</ulink>
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- All class files must contain a "file-level" docblock at the top of each file and a "class-level" docblock
|
|
|
- immediately above each class. Examples of such docblocks can be found below.
|
|
|
+ All class files must contain a "file-level" docblock at the top of each file and
|
|
|
+ a "class-level" docblock immediately above each class. Examples of such
|
|
|
+ docblocks can be found below.
|
|
|
</para>
|
|
|
</sect3>
|
|
|
|
|
|
@@ -726,8 +760,8 @@ switch ($numPeople) {
|
|
|
<title>Files</title>
|
|
|
|
|
|
<para>
|
|
|
- Every file that contains PHP code must have a docblock at the top of the file that
|
|
|
- contains these phpDocumentor tags at a minimum:
|
|
|
+ Every file that contains PHP code must have a docblock at the top of the file
|
|
|
+ that contains these phpDocumentor tags at a minimum:
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
/**
|
|
|
@@ -751,7 +785,8 @@ switch ($numPeople) {
|
|
|
<title>Classes</title>
|
|
|
|
|
|
<para>
|
|
|
- Every class must have a docblock that contains these phpDocumentor tags at a minimum:
|
|
|
+ Every class must have a docblock that contains these phpDocumentor tags at a
|
|
|
+ minimum:
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
/**
|
|
|
@@ -774,7 +809,8 @@ switch ($numPeople) {
|
|
|
<title>Functions</title>
|
|
|
|
|
|
<para>
|
|
|
- Every function, including object methods, must have a docblock that contains at a minimum:
|
|
|
+ Every function, including object methods, must have a docblock that contains at a
|
|
|
+ minimum:
|
|
|
|
|
|
<itemizedlist>
|
|
|
<listitem><para>A description of the function</para></listitem>
|
|
|
@@ -784,12 +820,14 @@ switch ($numPeople) {
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- It is not necessary to use the "@access" tag because the access level is already known
|
|
|
- from the "public", "private", or "protected" modifier used to declare the function.
|
|
|
+ It is not necessary to use the "@access" tag because the access level is already
|
|
|
+ known from the "public", "private", or "protected" modifier used to declare the
|
|
|
+ function.
|
|
|
</para>
|
|
|
|
|
|
<para>
|
|
|
- If a function/method may throw an exception, use @throws for all known exception classes:
|
|
|
+ If a function/method may throw an exception, use @throws for all known exception
|
|
|
+ classes:
|
|
|
|
|
|
<programlisting role="php"><![CDATA[
|
|
|
@throws exceptionclass [description]
|
thomas