Revision as of 13:14, 5 May 2009

Coding Guidelines for Geeklog

Geeklog originally didn't have any formal coding guidelines and so you may find different coding styles in different places. As of March 2007, all new code in Geeklog will have to follow the PEAR coding standards (see below for details).

Why have Code Conventions?

To quote from the Geeklog 2 Coding Standards:

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

• 80% of the lifetime cost of apiece of software goes to maintenance.
• Hardly any software is maintained for its whole life by the original author.
• Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly. If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create.

Why pick the PEAR coding standard?

Using the PEAR coding standard makes sense for several reasons:

• It's widely used and accepted in the PHP community.
• It's short and clear.
• Geeklog already uses some PEAR packages.
• Most of the code in Geeklog (apart from that based on lib-common.php) already uses a formatting style that's similar to the PEAR conventions.

PEAR Coding Standards

The following is about the actual source code formatting, i.e. how to place braces and what and how much whitespace to use. The PEAR naming conventions (file names, function names, etc.) are too different from Geeklog's and are not part of Geeklog's Coding Guidelines.

Specifically, we are adopting the following PEAR conventions:

• Indenting and Line Length (1)
• Control Structures (2)
• Function Calls (3)
• Function Definitions (4)
• Comments (5)
• Including Code (6)
• PHP Code Tags (7)
• File Formats (8)

To be defined: "Header Comment Blocks" (9). It may also make sense to adopt "E_STRICT-compatible code" (10) but that may be difficult to achieve in some contexts. It should certainly become a long-term goal, though.

Coding Guidelines

Indenting and Line Length

Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, CVS history and annotations.

For Emacs you should set indent-tabs-mode to nil. Here is an example mode hook that will set up Emacs (ensure that it is called when you are editing PHP files):

(defun php-mode-hook ()
  (setq tab-width 4
        c-basic-offset 4
        c-hanging-comment-ender-p nil
        indent-tabs-mode
  (not
    (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
      (string-match "\.php$" (buffer-file-name))))))

Here are Vim rules for the same thing:

set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4

It is recommended to keep lines at approximately 75-85 characters long for better code readability.

Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated of them:

<?php
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
?>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

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.

For switch statements:

<?php
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}
?>

Function Calls

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:

<?php
$var = foo($bar, $baz, $quux);
?>

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:

<?php
$short         = foo($bar);
$long_variable = foo($baz);
?>

Function Definitions

Function declarations follow the "BSD/Allman style":

<?php
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}
?>

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:

<?php
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;
}
?>

Comments

Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks (to be defined - Dirk) sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the phpDocumentor website.

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.

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.

Including Code

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.

Note: include_once and require_once are statements, not functions. Parentheses should not surround the subject filename.

PHP Code Tags

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

File Formats

All scripts contributed to Geeklog must:

• Be stored as ASCII text
• Use ISO-8859-1 character encoding (Exception: language files)
• Be Unix formatted
  "Unix formatted" means two things:
  1. Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.
  2. There should be one line feed after the closing PHP tag (?>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag.