[Summary view] [Print] [Text view]

   1  /**
   2  * +--------------------------------------------------------------------+
   3  * | MySource Matrix - Instructional Document                           |
   4  * +--------------------------------------------------------------------+
   5  *
   6  * $Id: commenting.txt,v 1.8 2005/01/20 13:37:16 brobertson Exp $
   7  *
   8  */
   9  
  10  +------------------------------------+
  11  | FUNCTION COMMENTING AND FORMATTING |
  12  +------------------------------------+
  13  
  14  General comments:
  15  ------------------------------------
  16  All comment lines should start with: "* " (note the space character after the astrix) - exccept for the first and last lines.
  17  All fucntions should have 2 blank lines between them. The first function in a class should have 2 blank lines before it and the last function in a class should have 2 blank lines after it.
  18  
  19  
  20  
  21  The comment header:
  22  ------------------------------------
  23  Line 1: /** <-- the start of the comment
  24  Line 2: *   <-- a ONE line sentence describing the purpose of the function
  25  Line 3: *   <-- a blank comment line
  26  
  27  <example>
  28  /**
  29  * Update the details of an existing link
  30  *
  31  </example>
  32  
  33  <comments>
  34  + No full stop after the one line purpose PLEASE
  35  </comments>
  36  
  37  Optional:
  38  The next section can be used to provide a larger description if required. The larger description can span many lines.
  39  
  40  <example>
  41  * If any of the detail vars are NULL they are not updated.
  42  * This is the case for all vars no matter what the type of the var is and
  43  * who created it.
  44  *
  45  </example>
  46  
  47  <comments>
  48  + Write full sentences here and keep the line lengths reasonable. You can always write on new lines, just be sure they start with "* " as well.
  49  + Make sure you leave the blank comment line after the detailed description section.
  50  </comments>
  51  
  52  
  53  
  54  Commenting the arguments:
  55  ------------------------------------
  56  All arguments of a function MUST be commented, no matter how obvious their purpose is.
  57  All arguments will be in the form:
  58  * @param [TYPE]    $[NAME]    [DESCRIPTION]
  59  
  60  Note the space after @param and the tab after TYPE and NAME
  61  
  62  For arguments that are references, ensure you place a "&" before "$[NAME]"
  63  
  64  For arguments where the type is an object, the [TYPE] becomes: object [CLASS NAME]
  65  If the class of the object could be one of many, choose the class of a common base class.
  66  If there is no common base class, [TYPE] becomes: object
  67  
  68  <example>
  69  * @param object Asset    &$asset        the asset to link up
  70  * @param int        $link_type    the type of the link (one of the SQ_LINK_* constants)
  71  * @param string        &$value        the value to place on the link
  72  * @param int        $sort_order    the position in the links list that this link should take,
  73  *                     if less than zero places at end of list
  74  </example>
  75  
  76  <comments>
  77  + Please ensure to keep the tabbing and spacing correct. It makes it much easier to read.
  78  </comments>
  79  
  80  
  81  
  82  The comment footer:
  83  ------------------------------------
  84  Line 1: * @return <-- the return value of the function
  85  Line 2: * @access <-- the access level of the function
  86  Line 3: */        <-- the end of the comment
  87  
  88  The comment footer must include the return type of the function and the access level to the function.
  89  Both these can be plain text - so you can write whatever you feel like, but for convention we use Private, Public, and Protected for the access level, and we use a [TYPE] (like in arguments) for the return value.
  90  
  91  <example>
  92  * @return Array(string)
  93  * @access public
  94  */
  95  </example>
  96  
  97  <example>
  98  * @return mixed int | false
  99  * @access private
 100  */
 101  </example>
 102  
 103  <example>
 104  * @return boolean - true on success, false on failure
 105  * @access protected
 106  */
 107  </example>
 108  
 109  <comments>
 110  </comments>
 111  
 112  
 113  
 114  Function formatting:
 115  ------------------------------------
 116  Every function should have be in the form:
 117  [COMMENT]
 118  function [NAME] ([ARGS])    <-- not the { is not on this line
 119  {                <-- its on this line instead
 120      [PHP CODE]        <-- code starts on the very next line
 121                  <-- a blank line is left before the }
 122  }//end [NAME]()            <-- no space after the } and // - plus
 123                      there are () on the end of the name,
 124                      no arguments are supplied here
 125  
 126  
 127  
 128  A complete example of a PHPDocumentor style commented function:
 129  ------------------------------------
 130  /**
 131  * Update the details of an existing link
 132  *
 133  * If any of the detail vars are NULL they are not updated.
 134  *
 135  * @param int    $linkid        the link id of the link to update
 136  * @param int    $link_type    the type of the link (one of the SQ_LINK_* constants)
 137  * @param string $value        the value to place on the link
 138  * @param int    $sort_order    the position in the links list that this link should take,
 139  *                 if less than zero places at end of list
 140  *
 141  * @return boolean
 142  * @access private
 143  */
 144  function _updateLink($linkid, $link_type=null, $value=null, $sort_order=null)
 145  {
 146      <PHP CODE HERE>
 147  
 148  }//end _updateLink()
 149  
 150  
 151  A more complex example:
 152  ------------------------------------
 153  /**
 154  * Create this asset
 155  *
 156  * The return value will be:<br/>
 157  * <ul>
 158  *   <li>FALSE if the asset was not created</li>
 159  *   <li>the ID of the newly created link if the asset and intital link were created</li>
 160  *   <li>TRUE if the asset was created but $link was empty</li>
 161  * </ul>
 162  *
 163  * @param Array    &$link    information used to create the initial link<br/>
 164  * <PRE>
 165  * Array ('asset'         => [ref major asset to create link under],
 166  *        'link_type'     => SQ_LINK_?,
 167  *        'value'         => [link value],
 168  *        'sort_order'    => [link sort order],
 169  *        'is_dependant'  => [0|1],
 170  *        'is_exclusive'  => [0|1]
 171  *        )
 172  * </PRE>
 173  *
 174  * @return mixed int or false
 175  * @access public
 176  */
 177  function create(&$link)
 178  {
 179      <PHP CODE HERE>
 180  
 181  }//end create()