Coding Standards

The purpose of this document is to lay out a clear set of guidelines for developing code for the AWF project. The scope of this document is limited mainly to PHP code, although AWF occasionally uses SQL and HTML.

Why have Coding Standards?

Code conventions are important to programmers for a number of reasons:

Acknowledgements

This document has been largely created by culling information from the following documents:

In some places we've copied it verbatim. Please don't sue us, we've got no money anyway. If you modify and redistribute this document please maintain the above credits and give us some also.

Indentation

One tab should be used for indentation:


function output_page_as_xml () {
    if(ALLOW_XML_OUTPUT) {
        foo();
        }
    else {
        echo 'Sorry.';
        }
    }

Line Length

Avoid lines greater than 100 characters. Yes, 100 not 80. We're in the new millenium now and we've got bigger screens.

Wrapping Lines

Here are some examples of breaking method calls:


someMethod(longExpression1, longExpression2, longExpression3, 
    longExpression4, longExpression5);
 
var = someMethod1(longExpression1,
    someMethod2(longExpression2,
     longExpression3));

Following are two examples of breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level.


longName1 = longName2 * (longName3 + longName4 - longName5)
                + 4 * longname6; // PREFER
 
longName1 = longName2 * (longName3 + longName4
                - longName5) + 4 * longname6; // AVOID

Following are two examples of indenting function declarations. The first is the conventional case. The second would shift the second and third lines to the far right if it used conventional indentation, so instead it indents only one tab.


// CONVENTIONAL INDENTATION
function someFunction($anArg, $anotherArg, $yetAnotherArg,
     $andStillAnother) {
     ...
     }
 
// INDENT TWO TABS TO AVOID VERY DEEP INDENTS
function superExtraHorkingLongMethodName($anArg, $anArg, $anArg,
          $anotherArg, $yetAnotherArg, $yetMoreArg, $anArg, $anArg
          $andStillAnother) {
      ...
      }

Line wrapping for if statements should generally use the two tabs rule, since conventional (one tab) indentation makes seeing the body difficult. For example:


// DON'T USE THIS INDENTATION
if ((condition1 && condition2)
     || (condition3 && condition4)
     ||!(condition5 && condition6)) { // BAD WRAPS
     doSomethingAboutIt();            // MAKE THIS LINE EASY TO MISS
     } 
 
// USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
          || (condition3 && condition4)
          ||!(condition5 && condition6)) {
     doSomethingAboutIt();
     } 
 
// OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
          ||!(condition5 && condition6)) {
     doSomethingAboutIt();
     }

Line Termination

Ensure that your editor is saving files in the Unix format. This means lines are terminated with a newline, not with a CR/LF combo as they are on Win32, or whatever the Mac uses. Any decent Win32 editor should be able to do this, but it might not always be the default. Know your editor.

Naming Convention

Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package, or class-which can be helpful in understanding the code.

In the block below, we'll refer to a capitalization strategy called StudlyCaps. In this strategy, multiple words are combined into one where the beginning of each internal word is capitalized. Acronyms are capitalized like regular words. For example a variable expressing the "maximum cpu speed" would be called $maximumCpuSpeed.

{|
!align="left"|Type !!align="left"|Description !!align="left"|Examples
|-
|Files || PHP files should end in .php. Files that are supposed to be included by a PHP script and contain PHP code should end in .inc. Files that contain a PHP class definition should contain a class of the same name as the file and end in .class. || AWF_ForumPosting.class, user_management.php, header.inc
|-
|Classes || Class names are in StudlyCaps and should be nouns. AWF's own classes should be prefixed with AWF followed by an underscore (_) (and use another prefix namespace for your own classes). Try to keep your class names simple and descriptive. Use whole words-avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML). || AWF_ForumPosting, AWF_PDF
|-
|Constants|| The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). Constants used in localization should begin with LANG_. || ALLOW_XML_OUTPUT, LANG_ADMIN_ADD_USER
|}

Class and Function Declarations

When coding classes and functions, the following formatting rules should be followed:

The above rules are sometimes referred to as the K&R style. Named after Kernighan & Ritchie, because the examples in K&R are formatted this way. Also called kernel style because the Unix kernel is written in it, and the "One True Brace Style" (abbrev. 1TBS) by its partisans. In C code, the body is typically indented by one tab per level, as shown here. Example:


class Foo {
    function getBar ($a, $b) {
        echo "$a => $b";
        }
    }

$myObject = new Foo;

$myObject->getBar('foo', 'bar');

Statements

Simple Statements

Each line should contain at most one statement. Example:


$argv++;                // Correct
$argc--;                // Correct

$argv++; $argc--;       // AVOID!

Compound Statements

Compound statements are statements that contain lists of statements enclosed in braces "{ statements }".

The enclosed statements should be indented one more level than the compound statement. The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement. Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.

return Statements

A return statement with a value should not use parentheses unless they make the return value more obvious in some way. Example:


return;
return $myDisk->size();
return ($argv * $argc - $defaultValue);

if, if-else, ifelse-if else Statements

The if-else class of statements should have the following form:


if (condition) {
    statements;
    }

if (condition) {
    statements;
    } 
else {
    statements;
    }
     
if (condition) {
    statements;
    } 
elseif (condition) {
    statements;
    } 
else {
    statements;
    }

Note: if statements always use braces {}. Avoid the following error-prone form:


if (condition) // AVOID! THIS OMITS THE BRACES {}!
    statement;

The ternary operator (example below) should not be used. Instead use an if-else statement.


$alpha = (booleanExpression) ? $beta : $gamma;   // AVOID!  Use if statement instead!

for Statements

A for statement should have the following form:


for (initialization; condition; update) {
    statements;
    }

An empty for statement (one in which all the work is done in the initialization, condition, and update clauses) should have the following form:


for (initialization; condition; update);

When using the comma operator in the initialization or update clause of a for statement, avoid the complexity of using more than three variables. If needed, use separate statements before the for loop (for the initialization clause) or at the end of the loop (for the update clause).

while Statements

A while statement should have the following form:


while (condition) {
    statements;
    }

An empty while statement should have the following form:


while (condition);

switch Statements

A switch statement should have the following form:


switch (condition) {
    case ABC:
        statements;
        /* falls through */

    case DEF:
        statements;
        break;

    case XYZ:
        statements;
        break;
     
    default:
        statements;
        break;
    }

Every time a case falls through (doesn't include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the /* falls through */ comment. Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.

White Space

Blank lines improve readability by setting off sections of code that are logically related. Two blank lines should always be used in the following circumstances:

One blank line should always be used in the following circumstances:

Blank Spaces

Blank spaces should be used in the following circumstances: A keyword followed by a parenthesis should be separated by a space. Example:


while (true) {
    ...
    }

Note that a blank space should not be used between a method name and its opening parenthesis. This helps to distinguish keywords from method calls. A blank space should appear after commas in argument lists. All binary operators except . should be separated from their operands by spaces. Blank spaces should never separate unary operators such as unary minus, increment ("++"), and decrement ("--") from their operands. Example:


$a += $c + $d;
$a = ($a + $b) / ($c * $d);
while ($n < $s) {
    $n++;
    }
print("size is ".$foo."n");

The expressions in a for statement should be separated by blank spaces. Example:


for (expr1; expr2; expr3)

Casts should be followed by a blank space. Examples:


myFunction((int) $a, (int) $b);

Comments

If you change code and/or write new code you should add appropriate comments. This applies to whole files (so called modules when we talk about procedural code, or classes when talking OO), function/method definitions, included files and important variables.

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged. Multiple line C-style comments should see the *'s aligned in a column (including the first line).

In addition, commenting any tricky, obscure, or otherwise not-immediately-obvious code is clearly something we should be doing. Especially important to document are any assumptions your code makes, or preconditions for its proper operation. Any one of the developers should be able to look at any part of the application and figure out what's going on in a reasonable amount of time.

Special Comments

Occasionally you wind up checking in code that's not totally satisfactory. Sometimes this is inevitable. In order to locate these bits of code so that we find and resolve it later, use the following tags in a comment, above the code in question:

Keep in mind that you may not get back to this code for a while. You may not even be the one to fix the thing, so the more information that you provide while it's still fresh in your mind, the better. Potential solutions or work arounds are great, and may prove invaluable to whomever gets around to addressing the issue.

If the comment isn't clear it may be ignored and eventually deleted.

At some point in the future this will enable us to dictate the following:

Associative Array Keys

In PHP, it's legal to use a literal string as a key to an associative array without quoting that string. We don't want to do this -- the string should always be quoted to avoid confusion. Note that this is only when we're using a literal, not when we're using a variable. Examples:


/* wrong */
$foo = $assoc_array[blah];
 
/* right */
$foo = $assoc_array['blah'];

Quoting Strings

There are two different ways to quote strings in PHP - either with single quotes or with double quotes. The main difference is that the parser does variable interpolation in double-quoted strings, but not in single quoted strings. Because of this, you should always use single quotes unless you specifically need variable interpolation to be done on that string. This way, we can save the parser the trouble of parsing a bunch of strings where no interpolation needs to be done. Also, if you are using a string variable as part of a function call, you do not need to enclose that variable in quotes. Again, this will just make unnecessary work for the parser. Note, however, that nearly all of the escape sequences that exist for double-quoted strings willnot work with single-quoted strings. Be careful, and feel free to break this guideline if it's making your code harder to read. Examples:


/* wrong */
$str = "This is a really long string with no variables for the parser to find.";
do_stuff("$str");
 
 /* right */
$str = 'This is a really long string with no variables for the parser to find.';
do_stuff($str);

Including Code

In most cases require_once() (http://php.net/require_once) should be used over include_once() (http://php.net/include_once). The two constructs are identical in every way except how they handle failure. include_once() produces a Warning while require_once() results in a Fatal Error. In other words, use require_once() if you want a missing file to halt processing of the page. include_once() does not behave this way, the script will continue regardless.

Note: include_once() and require_once() are statements, not functions. You don't need parentheses around the filename to be included.

PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

Uninitialized Variables

Don't use uninitialized variables. AWF uses a high level of run-time error reporting. This will mean that the use of an uninitialized variable will be reported as an error.

All variables should be initialized before use. Form variables should be referenced from the appropriate variable array. See the section on Register Globals.


if ($var) { // AVOID, unitialized variable
    ...something
    }
 
if (isset($var)) {  // OK
    ...soemthing
    }
 
$var = 1;
if ($var) {      // OK
    ...soemthing
    }

Register Globals

AWF is designed to work with register globals disabled. To access GET, POST and COOKIE variables use the $_GET, $_POST, and $_COOKIE global arrays respectively. Alternatively the $_REQUEST global array variable can be used; it merges the $_GET, $_POST, and $_COOKIE arrays.

Note: Keep in mind that the precedence of $_REQUEST is defined in the php.ini file and may not be what you expect.

Sessions

AWF uses PHP sessions for session management. The $_SESSION array will be available globally for storing session data. Since session information will be stored in a database, the size of data kept in the $_SESSION array should be kept as small as possible.

Magic Numbers

Don't use them. Use named constants for any literal value other than obvious special cases. Basically, it's OK to check if an array has 0 elements by using the literal 0. It's not OK to assign some special meaning to a number and then use it everywhere as a literal. This hurts readability AND maintainability. Included in this guideline is that we should be using the constants TRUE and FALSE in place of the literals 1 and 0 -- even though they have the same values, it's more obvious what the actual logic is when you use the named constants.

Shortcut operators

The only shortcut operators that cause readability problems are the shortcut increment ($i++) and decrement ($j--) operators. These operators should not be used as part of an expression. They can, however, be used on their own line. Using them in expressions is just not worth the headaches when debugging. Examples:


/* wrong */
$array[++$i] = $j;
$array[$i++] = $k;
 
/* right */
$i++;
$array[$i] = $j;
    
$array[$i] = $k;
$i++;

Operator Precedence

Do you know the exact precedence of all the operators in PHP? Neither do I. Don't guess. Always make it obvious by using brackets to force the precedence of an equation so you know what it does.


/* what's the result? who knows. */
$bool = ($i < 7 && $j > 8 || $k == 4);
    
/* now you can be certain what I'm doing here. */
$bool = (($i < 7) && (($j < 8) || ($k == 4)))

PDF version

Created: 07.01.2006 22:01 CET, Last Change: 09.01.2006 15:12 CET by admin

Wiki Navigation

Language

Login

or create a new account

Username


Password