|
From: Benjamin C. <bc...@us...> - 2001-09-19 14:21:37
|
Update of /cvsroot/phpbt/phpbt/docs/sgml
In directory usw-pr-cvs1:/tmp/cvs-serv3435/sgml
Added Files:
devstandards.sgml
Log Message:
Beginnings of the documentation
--- NEW FILE: devstandards.sgml ---
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
[
<!ENTITY phpbt "phpBugTracker">
]>
<article id="devstandards" xreflabel="Development Standards">
<articleinfo>
<title>Development Standards</title>
<abstract>
<para>
This document will contain the coding and process standards to be
followed by the developers working on &phpbt;.
</para>
</abstract>
</articleinfo>
<sect1 id="devstandards-code" xreflabel="Coding Standards">
<title>Coding Standards</title>
<sect2 id="devstandards-indenting" xreflabel="Indenting">
<title>Indenting</title>
<para>
Use an indent of one tab per indent.
</para>
</sect2>
<sect2 id="devstandards-control" xreflabel="Control Structures">
<title>Control Structures</title>
<para>
These include if, for, while, switch, etc. Here is an example if
statement, since it is the most complicated of them:
</para>
<programlisting>
if ((condition1) || (condition2)) {
action1;
} elseif ((condition3) && (condition4)) {
action2;
} else {
defaultaction;
}
</programlisting>
<para>
Control statements should have one space between the control keyword
and opening parenthesis, to distinguish them from function calls.
</para>
<para>
You are strongly encouraged to always 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.
</para>
</sect2>
<sect2 id="devstandards-funccalls" xreflabel="Function Calls">
<title>Function Calls</title>
<para>
Functions should 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:
</para>
<programlisting>
$var = foo($bar, $baz, $quux);
</programlisting>
<para>
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.
</para>
</sect2>
<sect2 id="devstandards-funcdefs" xreflabel="Function Definitions">
<title>Function Calls</title>
<para>
Function definitions follow the format of function calls, with the
opening brace at the end of the line of the function declaration. The
global variable list (if used) should be placed on the line immediately
following the opening brace, with a blank line between the variable
list and the first line of function code. If the global variable list
is not neccessary, include a blank line between the opening brace and
the first line of function code.
</para>
<programlisting>
function fooFunction($arg1, $arg2 = '') {
global $foo1, $foo2;
if (condition) {
statement;
}
return $val;
}
</programlisting>
<para>
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:
</para>
<programlisting>
function connect(&$dsn, $persistent = false) {
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}
if (!$dsninfo || !$dsninfo['phptype']) {
return $this->raiseError();
}
return true;
}
</programlisting>
</sect2>
<sect2 id="devstandards-comments" xreflabel="Comments">
<title>Comments</title>
<para>
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.
</para>
</sect2>
<sect2 id="devstandards-including" xreflabel="Including Code">
<title>Including Code</title>
<para>
Anywhere you are unconditionally including a class file, use
<ulink url="http://php.net/manual/en/html/function.require-once.html">
<function>require_once()</function></ulink>. Anywhere you are
conditionally including a class file (for example, factory methods),
use <ulink url="http://php.net/manual/en/html/function.include-once.html">
<function>include_once()</function></ulink>. 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 <function>require_once()</function> will not be included again by
<function>include_once()</function>.
</para>
</sect2>
<sect2 id="devstandards-phptags" xreflabel="PHP Tags">
<title>PHP Tags</title>
<para>
Always use <computeroutput><![CDATA[<?php ?>]]></computeroutput>
to delimit PHP code, not the <computeroutput><![CDATA[<? ?>]]></computeroutput>
shorthand.
</para>
</sect2>
<sect2 id="devstandards-constants" xreflabel="Naming Constants">
<title>Naming Constants</title>
<para>
Constants should always be uppercase, with underscores to separate
words.
</para>
</sect2>
</sect1>
<sect1 id="devstards-otherconventions" xreflabel="Other Conventions">
<title>Other Conventions</title>
<sect2 id="devstandards-filenaming" xreflabel="File Naming">
<title>File Naming</title>
<para>
File names should be all lowercase and contain no spaces. HTML files
should have <filename>.html</filename> as the extension, and PHP files
should have <filename>.php</filename> as the extension. Where possible,
template files should match the name of the PHP file that will be using
it, e. g., <filename>index.html</filename> would be the template file
for <filename>index.php</filename>. Where one PHP file uses more than one
templates, the templates should be similarly named:
<filename>user.php</filename> could use
<filename>userlist.html</filename> and <filename>userform.html</filename>
for a list of users and editing a user, respectively.
</para>
</sect2>
</sect1>
</article>
|