Code commenting with Doc Blocks

Code commenting can be a pain. If its your code then you know exactly what it does and why. If its someone else’s code – then all of a sudden they are invaluable. The Doc Block commenting style is a widely used standard for commenting accross all languages, and can also be used to generate code hints and automatic documentation if used properly.

The following guide to code-commenting is taken from: http://net.tutsplus.com/tutorials/php/object-oriented-php-for-beginners/

The real power of DocBlocks comes with the ability to use tags, which start with an at symbol (@) immediately followed by the tag name and the value of the tag. DocBlock tags allow developers to define authors of a file, the license for a class, the property or method information, and other useful information.

The most common tags used:

@author: The author of the current element (which might be a class, file, method, or any bit of code) are listed using this tag. Multiple author tags can be used in the same DocBlock if more than one author is credited. The format for the author name is John Doe .
@copyright: This signifies the copyright year and name of the copyright holder for the current element. The format is 2010 Copyright Holder.
@license: This links to the license for the current element. The format for the license information is
http://www.example.com/path/to/license.txt License Name.
@var: This holds the type and description of a variable or class property. The format is type element description.
@param: This tag shows the type and description of a function or method parameter. The format is type $element_name element description.
@return: The type and description of the return value of a function or method are provided in this tag. The format is type return element description.


 
 * @copyright 2010 Some Design Company
 * @license http://www.php.net/license/3_01.txt PHP License 3.01
 */

class SimpleClass
{
    /**
     * A public variable
     *
     * @var string stores data for the class
     */
    public $foo;

    /**
     * Sets $foo to a new value upon class instantiation
     *
     * @param string $val a value required for the class
     * @return void
     */
    public function __construct($val)
    {
        $this->foo = $val;
    }

    /**
     * Multiplies two integers
     *
     * Accepts a pair of integers and returns the
     * product of the two.
     *
     * @param int $bat a number to be multiplied
     * @param int $baz a number to be multiplied
     * @return int the product of the two parameters
     */
    public function bar($bat, $baz)
    {
        return $bat * $baz;
    }
}

?>