1 <?xml version='1.0' encoding='UTF-8'?>
2 <section id="cg_coding_standards">
3 <title>PHP Coding Standards</title>
5 <title>Introduction</title>
7 Coding Standards. Live them, love them.
10 Then come up with a new introduction...
14 <title>Comments</title>
16 <title>Guidelines</title>
18 Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.
22 <para>C++ style comments (/* */) and standard C comments (//) are both acceptable.</para>
25 <para>Use of perl/shell style comments (#) is prohibited.</para>
30 <title>PHPdoc Tags</title>
32 Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: <ulink url="http://www.phpdoc.de/">http://www.phpdoc.de/</ulink>
36 <title>File comments</title>
38 Every file should start with a comment block describing its purpose, version, author and a copyright message. The comment block should be a block comment in standard JavaDoc format along with a CVS Id tag. While all JavaDoc tags are allowed, only the tags in the examples below will be parsed by PHPdoc.
41 FusionForge contains a mixed copyright. For files that have been changed since the FusionForge fork, the following header should be used:
43 <programlisting><![CDATA[
47 * long description. more long description.
49 * Portions Copyright 1999-2001 (c) VA Linux Systems
50 * The rest Copyright 2002 (c) their respective authors
56 <title>Function and Class Comments</title>
58 Similarly, every function should have a block comment specifying name, parameters, return values, and last change date.
60 <programlisting><![CDATA[
63 * long description. more long description.
65 * @author firstname lastname email
66 * @param variable description
67 * @return value description
78 The placement of periods in the short and long descriptions is important to the PHPdoc parser. The first period always ends the short description. All future periods are part of the long description, ending with a blank comment line. The long comment is optional.
83 <title>Formatting</title>
85 <title>Indenting</title>
87 All indenting is done with TABS. Before committing any file to Subversion, make sure you first replace spaces with tabs and verify the formatting.
91 <title>PHP Tags</title>
93 The use of <markup><?php ?></markup> to delimit PHP code is required. Using <markup><? ?></markup> is not valid. This is the most portable way to include PHP code on differing operating systems and webserver setups. Also, XML parsers are confused by the shorthand syntax.
98 <title>Templating</title>
100 In the FusionForge system, PHP itself is used as the template language. To make the templating clearer, template files should be separated out and included once objects and database results are established. Detailed examples are in the docs repository and <link linkend="cg_templating">here</link>.
103 Variables in the templates are presented surrounded by <markup> <?php ?></markup> tags instead of the {} tags that some other template libraries would use. The end result is the same, with less bloat and more efficient code.
107 <title>Expressions</title>
110 <para>Use parentheses liberally to resolve ambiguity.</para>
113 <para>Using parentheses can force an order of evaluation. This saves the time a reader may spend remembering precedence of operators.</para>
116 <para>Don't sacrifice clarity for cleverness.</para>
119 <para>Write conditional expressions so that they read naturally aloud.</para>
122 <para>Sometimes eliminating a not operator (!) will make an expression more understandable.</para>
125 <para>Keep each line simple.</para>
128 <para>The ternary operator (x ? 1 : 2) usually indicates too much code on one line. if... else if... else is usually more readable.</para>
133 <title>Functions</title>
135 <title>Function Calls</title>
137 unctions shall be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:
139 <programlisting><![CDATA[
140 $var = foo($bar, $baz, $quux);
143 As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:
145 <programlisting><![CDATA[
147 $long_variable = foo($baz);
151 <title>Function Definitions</title>
153 Function declarations follow the unix convention:
155 <programlisting><![CDATA[
156 function fooFunction($arg1, $arg2 = '') {
165 Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:
167 <programlisting><![CDATA[
168 function connect(&$dsn, $persistent = false) {
169 if (is_array($dsn)) {
172 $dsninfo = DB::parseDSN($dsn);
175 if (!$dsninfo || !$dsninfo['phptype']) {
176 return $this->raiseError();
185 <title>Objects</title>
187 Objects should generally be normalized similar to a database so they contain only the attributes that make sense.
190 Each object should have <classname>Error</classname> as the abstract parent object unless the object or its subclasses will never produce errors.
193 Each object should also have a <methodname>create()</methodname> method which does the work of inserting a new row into the database table that this object represents.
196 An <methodname>update()</methodname> method is also required for any objects that can be changed. Individual <methodname>set()</methodname> methods are generally not a good idea as doing separate updates to each field in the database is a performance bottleneck.
199 <methodname>fetchData()</methodname> and <methodname>getId()</methodname> are also standard in most objects. See the tracker codebase for specific examples.
202 Common sense about performance should be used when designing objects.
206 <title>Naming</title>
210 Constants should always be uppercase, with underscores to separate words. Prefix constant names with the name of the class/package they are used in. For example, the constants used by the DB:: package all begin with <quote>DB_</quote>.</para>
214 True and false are built in to the php language and behave like constants, but should be written in lowercase to distinguish them from user-defined constants.
219 Function names should suggest an action or verb: <function>updateAddress</function>, <function>makeStateSelector</function>
224 Variable names should suggest a property or noun: <varname>UserName</varname>, <varname>Width</varname>
229 Use pronounceable names. Common abbreviations are acceptable as long as they are used the same way throughout the project.
234 Be consistent, use parallelism. If you are abbreviating <quote>number</quote> as <quote>num</quote>, always use that abbreviation. Don't switch to using <quote>no</quote> or <quote>nmbr</quote>.
239 Use descriptive names for variables used globally, use short names for variables used locally.
241 <programlisting><![CDATA[
242 $AddressInfo = array(...);
244 for($i=0; $i < count($list); $i++)
250 <title>Control Structures</title>
252 These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated form:
254 <programlisting><![CDATA[
255 if ((condition1) || (condition2)) {
257 } elseif ((condition3) && (condition4)) {
264 Control statements shall have one space between the control keyword and opening parenthesis, to distinguish them from function calls.
267 You should use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.
270 For switch statements:
272 <programlisting><![CDATA[
290 <title>Including PHP Files</title>
292 Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file (for example, factory methods), use include_once. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once will not be included again by include_once.
296 Note: include_once and require_once are statements, not functions. You don't need parentheses around the filename to be included, however you should do it anyway and use ' (apostrophes) not " (quotes):
299 <programlisting><![CDATA[