Programming Style

From GeeklogWiki
Revision as of 20:51, 28 June 2004 by Tomw (talk | contribs) (=Naming Convention:=)

Jump to: navigation, search

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. You should see that documentation for examples if you have any questions. It can be found at http://pear.php.net/manual/en/standards.php.


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 PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://phpdocu.sourceforge.net/. Note: the documentation files for lib-common.php and lib-security.php were generated directly from the source files by PHPDocu.


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 seach path. Many PHP implementations 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:

include($_CONF['path_html'] . "/myblock/mb_functions.php");



PHP Code Tags:

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