Style Guide for PHP Comments

The comment styles listed below follow the standards used by PHPDoc.

Example of File Header

/**
* the_file_name.php
* This file does lots of stuff like blah blah blah
* @version 1.0
* @package ocfit_inventory - if the file contains classes specify 'ocfit_inventory' as the class package

*/

Example of Includes

/**
* Description of file to include

*/
include_once 'somefile.php';

Example of GLOBALS

/**
* Special global variable declaration
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;

Example of Constants

/**#@+
* Constants
*/

/**

* first constant
*/
define('firstconstant', 6);

/**

* second constant
*/
define('secondconstant', strlen('hello'));

/**
* Description of the function
* @global - if the function uses the globals declare each global on a separate line
* @staticvar - datatype - if the function uses static variables declare each static variable on a separate line

* @param string - $param1 description of first param
* @param string - $param2 description of second param
* @return integer - datatype returned
*/
function firstFunc($param1, $param2 = 'optional') {

  static $staticvar = 7;
  global $_myvar;

  return $staticvar;
}

Example of Class

/**
* Description of the class
* @package ocfit_inventory
* @subpackage - specify subpackage (i.e. logical_layer, data-access_layer, data_model)
*/
class myclass {

// PROPERTIES

/**

• • Description of property
    
  • @access public - <type of access>
    

• • @var integer - <datatype>
    */
    public var $firstvar = 6;

     

// CONSTRUCTOR

/**

• • Constructor for <classname>
    
  • @param string $param1 description of first param
    
  • @param string $param2 description of second param
    

• • @return integer data type returned
    */
    public function __construct($param1, $param2) {
    

. . .
}

// METHODS

/**

• • Description of the function
    
  • @param string $param1 description of first param
    

• • @param string $param2 description of second param
    
  • @return integer data type returned
    */
    public function memberFunc($param1, $param2 ) {
    

  return 6;
}

}