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.
Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.de/
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 $ * */
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 * */