Dev CodingGuidelines Comments

Table of Contents Developer pages: Coding Guidelines Comments PHP-Doc Inline comments Type hint comments

Developer pages: Coding Guidelines

Comments

PHP-Doc

For doc comments phpDocumentor is used. The following elements of a file are documented:

• the file itself
• classes
• interfaces
• methods
• properties
• class constants

Complete doc comments must be provided. A file with PHP doc comments looks like this:

<?php
/**
*Short description of file - most times this is identical with class description.
 *
*Optional long description about file contents - no class specific descriptions.
 *
*@package     stubbles
*@subpackage  examples
*@version     $Id$
*/
stubClassLoader::load('net::stubbles::lang::stubRegistry');
/**
*Short description of class.
 *
*Optional detailed description of class.
 *
*@package     stubbles
*@subpackage  examples
*/
class Example extends stubBaseObject
{
    /**
***description of property
     *
***@var string
***/
    protected $command = '....';

    /**
***short description of method
     *
***Optional long description of method.
     *
***@param   string         $date
***@return  array<string>
***/
    function getData($date)
    {
        return array();
    }
}
?>

Please note: space between annotation and next field is at least two spaces. Each column should start on the same level. In the example above this means the @subpackage is followed by two spaces. For the @package annotation this means it has five spaces so that its content starts on the same level as the content of the @subpackage annotation. The usage of the @author annotation is discouraged, no authors in source files.

Other doc comment annotations may be used as they are reasonable.

For array types the content of the array should be commented as follows:

• array<string>: numeric array containing only strings.
• array<string,Example>: associative array where the key is a string and the value is of type Example.

Beside PHP types and class names the following types may be used as well:

• mixed: allows any type
• scalar: allows scalar types: string, int, float, bool and null

Inline comments

For inline comments only // is allowed:

// check, whether user is logged in
if ($user->isAuthenticated()) {
    ...
} 

The // must be followed by a space.

In development phase comments can be made with #. This should indicate that something still needs to be implemented or changed. If such comments are used, the method doc comment must have a @todo annotation explaining what is missing:

/**
*a function to do something
 *
*@return  bool
*@todo    finish implementation
*/
function doSomething()
{
    if ($user->isAuthenticated()) {
        # do something here
        # log what has been done to something.log
    } else {
        # do other things here
    }

    return true;
} 

Type hint comments

Some IDEs support type hint comments which may be used in foreach loops for instance:

foreach ($profiles as $profile) {
    /* @var  $profile  StatsalyzerNgProfile */
    $profile->doSomething();
}

By adding such a comment the IDE knows about the type of $profile and is able to provide code completion to the developer. It is as well helpful for other developers as they can see now more easily what's going on here.

Next: Control structures

---
Back to developer pages