Coding Style Guide

In the hope that more of you will contribute code to the Onto Wiki project we are providing a coding style guide with this release. It mainly follows the PEAR Coding Standards so we only point out the differences in this document.

Contents

Indentation and Line Length

Function Definitions

Indentation and Line Length

Indentation level should be 4 spaces or 1 tab if you like. An average line should not be longer than 100 characters with 120 characters beeing the maximum.

Function Definitions

Function definitions follow the SUN/Java style:


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

Operators

All operators have to be surrounded with spaces.


<?php
$foo = $this->getFooVar();
$bar = $this->getBarVar() . ' appended to bar';

for ($i = 0; $i < 100; ++$i) {
    echo ($i + 7 % 3);
}
?>

Type Hinting

You are highly encouraged to use type hinting that was introduced with PHP 5. Type hinting allows you to request function parameters passed to be of a certain type. If a wrong type is passed, PHP throws a runtime error. Type hinting only works with objects or arrays, i.e. you can specify the exact class name of which passed objects need to be an instance or you use the type array.


<?php
public function myFunc(RDFSClass $class, array $values) {
    // now we can safely assume an array
    foreach ($values as $val) {
        // ...
    }
}
?>

Class Naming

In order to make classes auto-loadable, please use the following scheme for class-names:


<?php
class Erfurt_ExamplePackage_ExampleClass {
// ...
}
?>

Every class starts with the Erfurt prefix followed by an underscore.
The second part of the name is the name of the package the class belongs to (in this case examplepackage).
The third part of the name is the real name of your class (in this case ExampleClass).

Please also note the following:

The name of a class and it's position in the file system should directly adhere, i.e. for the above example, the corresponding class should be located in Erfurt/ExamplePackage/ExampleClass.php.
In case a class should belong to the default package (erfurt) the class would be named as followed:


<?php
class Erfurt_ExampleClass {
// ...
}
?>

Each file correspondends to exactly one class.

Inline Documentation

Classes

Every class should be documented as followed:


<?php
/**
 * The first sentence is the short description followed by a break.
 *
 * The second clause and all following sentences are for a detailed description of
 * the class. Feel free to document your class and the function of it as detailed as 
 * possible, such that other developers or end-users have a good basis. 
 *
 * @package examplepackage
 * @author Philipp Frischmuth <philipp@frischmuth24.de>
 * @author MaybeAnotherAuthor <with.another@email.address>
 * @copyright Copyright (c) <YEAR_OF_CREATION> - <CURRENT_YEAR>, {@link http://aksw.org AKSW}
 * @license http://opensource.org/licenses/gpl-license.php GNU General Public License (GPL)
 * @see http://example.com/doc/ExternalLibraryClass.html
 * @version $Id: $
 */
class Erfurt_ExamplePackage_ExampleClass extends ExternalLibraryClass {
// ..
}
?>

Please note the following:

The first sentence of the comment is always the short description.
Each following sentence belongs to the detailed description of the class.
Please insert an empty line between short description and detailed description and between detailed description and following tags.
Always use the @package tag. In case the class belongs to the default package use @package erfurt.
Use a new @author tag for each author.
Use the @copyright tag as above, but just use the current year in case current year and year of creation are equal.
Always use the @license tag, for we do without the GPL preamble.
In case your class extends or implements a unknown class (e.g. the class/interface belongs to an external library) use the @see tag together with an URL pointing to the documentation of that class or interface.
Use the @version tag as above, but also set the svn:keywords property if you are adding a new class: svn propset svn:keywords Id Erfurt / Example Package / Example Class.php

There are no files on this page. [Display files/form]

There is no comment on this page. [Display comments/form]

Information

Last Modification: 2009-05-08 17:46:49 by Sebastian Dietzold