Home>

...

>

Commenting

Commenting

In this lesson we will look at how to write code comments in PHP.

Code Comments

In general, code should be commented prolifically. It not only helps describe the flow and intent of the code for less experienced programmers but can prove invaluable when returning to your own code months down the line. There is not a required format for comments, but the following are recommended.

DocBlock style comments preceding class, method, and property declarations so they can be picked up by IDEs:

PHP
/**
 * Super Class
 *
 * @package     Package Name
 * @subpackage  Subpackage
 * @category    Category
 * @author      Author Name
 * @link        http://example.com
 */
class Super_class {
PHP
/**
 * Encodes string for use in XML
 *
 * @param       string  $str    Input string
 * @return      string
 */
function xml_encode($str)
PHP
/**
 * Data for class manipulation
 *
 * @var array
 */
public $data = array();

Use single line comments within code, leaving a blank line between large comment blocks and code.

PHP
// break up the string by newlines
$parts = explode("\n", $str);
// A longer comment that needs to give greater detail on what is
// occurring and why can use multiple single-line comments.  Try to
// keep the width reasonable, around 70 characters is the easiest to
// read.  Don't hesitate to link to permanent external resources
// that may provide greater detail:
//
// http://example.com/information_about_something/in_particular/
$parts = $this->foo($parts);