Difference between revisions of "Programming Style"

Latest revision as of 17:53, 21 May 2009

Good coding style makes your code more easily readable, fixable and modifiable by other people. It is strongly encouraged. It is a goal to which we all strive and seldom reach. We encourage you to practice good coding style. At the very least, correctly indent your code.

The following coding style suggestions are mostly adapted from the PHP PEAR project. The PEAR coding style has also been adopted as the official Geeklog Coding Guidelines.

Naming Convention

Choose a short prefix for all your global functions and variables. This makes it easy to determine where a particular function or variable came from. It also prevents naming collisions which are difficult to debug. Note that Geeklog itself follows this convention, e.g. all functions from lib-common.php start with COM_. In the Contact plugin the prefix CT_ was used. It can also help to prefix all global variables with an underscore, so global variables in the Contact plugin start with $_CT_.

Geeklog uses this convention of any underscore and capital letters to indicate a global variable e.g. $_TABLES, $_CONF, $_USER variables.

Indenting

Use an indent of 4 spaces, with no tabs. Please indent your code.

Control Structures

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

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

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:

$var = foo($bar, $baz, $quux);

Function Declarations

Function declarations follow the "one true brace" convention:

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

Comments

Inline documentation for classes should follow the phpDocumentor convention, which is similar to Javadoc. Also see Source Code Documentation.

Note: the documentation files for lib-common.php and lib-security.php were generated directly from the source files by phpDocumentor.

Including Code

Anywhere you are unconditionally including a class or library file, use require_once. Anywhere you are conditionally including a class or library file, use include_once.

Additionally it is recommended that all of your project includes use the fully qualified path to the include file instead of assuming the user has the current directory in the search path. Many PHP installations don't include the current directory in the path and statements such as include 'myfunctions.php' will fail. Use the $_CONF['path_html'] variable in the include statement.

Example:

require_once '../lib-common.php';
include $_CONF['path_html'] . '/myblock/mb_functions.php';

Please note that $_CONF['path_html'] is only available after you have included lib-common.php.

PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand.