3.2. Comments

3.2.1. Guidelines

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

  • C++ style comments (/* */) and standard C comments (//) are both acceptable.

  • Use of perl/shell style comments (#) is prohibited.

3.2.2. PHPdoc Tags

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.de/

3.2.3. File comments

Every file should start with a comment block describing its purpose, version, author and a copyright message. The comment block should be a block comment in standard JavaDoc format along with a CVS Id tag. While all JavaDoc tags are allowed, only the tags in the examples below will be parsed by PHPdoc.

GForge contains a mixed copyright. For files that have been changed since the GForge fork, the following header should be used:

/**
 *
 * brief description.
 * long description.  more long description.
 *
 * Portions Copyright 1999-2001 (c) VA Linux Systems
 * The rest Copyright 2002 (c) their respective authors
 *
 * @version   $Id: coding_standards.xml,v 1.1 2004/03/02 16:58:39 gsmet Exp $
 *
 */

3.2.4. Function and Class Comments

Similarly, every function should have a block comment specifying name, parameters, return values, and last change date.

/**
 * brief description.
 * long description.  more long description.
 *
 * @author    firstname lastname email
 * @param     variable  description
 * @return    value     description
 * @date      YYYY-MM-DD
 * @deprecated
 * @see
 *
 */

3.2.5. Note

The placement of periods in the short and long descriptions is important to the PHPdoc parser. The first period always ends the short description. All future periods are part of the long description, ending with a blank comment line. The long comment is optional.