More.groupware coding conventions

From MGWiki

This is a first step of guidance to a more clear programming. It is taken from the PEAR Coding Standards which can be found at http://pear.php.net/manual/en/standards.php . These are only excerpts from that to make the main parts clear. Indenting

Contents 1 Use an indent of 4 spaces, with no tabs. 2 Naming conventions 3 Constants 4 Global variables 5 Control structures 6 Function calls 7 Comments 8 Including code 9 PHP code tags 10 Using CVS 11 General script structure

Use an indent of 4 spaces, with no tabs.

For UltraEdit 32 (on Windows) Go to Advanced -> Configuration and choose the Edit tab. Check "Use spaces in place of tabs" and enter 4 in the next text field which should say something like "Tab Stop Value" + an excessive bunch of words. If you've already written code with other tab stops follow the above note and then do Format > Tabs to Spaces For hints on other editors go to the URL shown above.

Naming conventions

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). Functions should in addition have the package name as a prefix, to avoid name collisions between packages. The initial letter of the name (after the prefix) is lowercase, and each letter that starts a new "word" is capitalized. Some examples:

connect()
getData()
buildSomeWidget()
XML_RPC_serializeData()

Private class members (meaning class members that are intented to be used only from within the same class in which they are declared; PHP does not yet support truly-enforceable private namespaces) are preceeded by a single underscore. For example:

_sort()
_initTree()
$this->_status

Constants

Constants should always be all-uppercase, with underscores to seperate words. Prefix constant names with the uppercased name of the class/package they are used in. For example, the constants used by the DB:: package all begin with "DB_".

Global variables

If your package needs to define global variables, their name should start with a single underscore followed by the package name and another underscore. For example, the PEAR package uses a global variable called $_PEAR_destructor_object_list.

Control structures

This is a complete if-example:

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

For switch statements:

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:

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

Comments

Inline documentation for classes should follow the PHPDocumentor convention, similar to Javadoc. More information about PHPDocumentor can be found at the project homepage or at the sf.net project page.

Usage hints are available in large quantities through Google: http://www.google.com/search?q=using+phpdocumentor.

C style comments (/* */) and standard C++ comments (//) are both fine for shorter comments, too. Use of Perl/shell style comments (#) is strongly 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().

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.

You should switch the short open tag off during development.

Using CVS

Include the Id CVS keyword in each file. As each file is edited, add this tag if it's not yet present (or replace existing forms such as "Last Modified:", etc.).

General script structure

Additions to the PEAR conventions:

**********
inclusion:
**********

global parameters:

$myEnv[module] = "contact";
$myEnv[output] = "html";

include('MGW_vCard.php');

(export classes and functions that are to be reused in another context to a separate class of file).

********
control:
********

if (isset($dump)){
  dumpVCard($id, $PHPSESSID);
} else {
  exportVCard($id, $PHPSESSID);
}

(which will be more complex in other modules, but shows at the beginning of the page what functions to expect)

***************
implementation:
***************

/**
* Exports a vCard (first line is short description!)
*
* Some longer description about the method, may have
* multiple lines.
*
* @param int $id The id of the card to export (this describes the parameter)
* @param string $PHPSESSID The current session id (this describes the parameter)
* @return string The finished card (this describes the return value, use void if nothing is returned)
function exportVCard($id, $PHPSESSID){
  ...
}

/**
* Exports and prints a vCard (first line is short description!)
*
* Some longer description about the method, may have
* multiple lines.
*
* @param int $id The id of the card to export (this describes the parameter)
* @param string $PHPSESSID The current session id (this describes the parameter)
* @return void
function dumpVCard($id, $PHPSESSID){
  ...
}

Clearly define interfaces (what parameters we need to make the function work and to improve testing of single methods).