Last Updated: 20 Oct 2023

   |   

Author: 135.181.114.235

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
Last revision Both sides next revision
processes:code-documentation-standards [May 9, 2009 11:02 PM]
dordal 		processes:code-documentation-standards [Oct 20, 2023 12:07 PM]
111.225.149.204 removed
Line 1: Line 1:
 += Code Documentation Standards =
  
 +Documenting your code well is almost as important as making sure it is bug free. In fact, many people would argue that it is //more// important, because if you document it well, at least somebody else can come in and fix your bugs later on.
 +
 +I like using the *doc format for code documentation ([[http://www.phpdoc.org/|phpdoc]], [[http://java.sun.com/j2se/javadoc/|javadoc]], etc.) because it is fairly standard and easily machine+human readable. It uses ''@'' identifiers for various peices of documentation (e.g. ''@param'', ''@return'', ''@see'', etc.)
 +
 +For the code itself, I try to follow the [[http://framework.zend.com/manual/en/coding-standard.html|Zend Framework standards]]. In brief, these are:
 + * Lines should be 75-85 characters long, no more. Four spaces should be used for indentation, not tabs.
 + * One class per file. 
 + * Underscores in class names map to directory separators (e.g. ''Zend_Controller_Action'' maps to ''Zend/Controller/Action.php'')
 + * Class names are all MixedCase. Curly bracket to open a class appears on the line after the class definition.
 + * Method names are all camelCase. Curly brackets appear on the same line as the method definition.
 + * Constants are ALL_CAPS, with underscores for spaces.
 + * Properties and variable names are camelCase. Private and protected properties start with an underscore (e.g. ''private $_myVar'')
 +
 +For a great overview of code+documentation best practices in PHP (as well as other PHP best practices), see  Matthew Weier O'Phinney's [[http://www.slideshare.net/dpc/best-practices-with-zend-framework-matthew-weier-ophinney|Best Practices with Zend Framework]] slideshow.
 +
 +The following is a code sample outlining good code+documentation practices. It is written in PHP, but the concepts can be applied to any similar language. Note the ''$Id: $'' tag; I generally like to [[:server-tech:subversion:setting-the-id-tag|configure subversion to automatically set that tag]].
 +
 +<code php>
 +<?php
 +
 +/**
 + * MyBigClass 
 + * 
 + * MyBigClass lets you do great things. Note we try to keep all lines, including comments, 
 + * under 75-85 chars
 + * 
 + * @author David Ordal, david -at- ordal.com
 + * @package bigclass-tool
 + * @version $Id: mybigclass.php 3259 2009-03-15 22:54:21Z dordal $
 + *
 + */
 +
 +// class names are declared in MixedCase, and the open bracket goes on the next line
 +class MyBigClass 
 +{
 +    
 +    // constants are declared in ALL_CAPS
 +    const AW_LANGUAGES = 'en';
 +    const AW_COUNTRIES = 'US';
 +    
 +    public $setupList = null;              // variables are declared in camelCase
 +    private $_apiSoapClient = null;        // and private/protected variables start with an
 +                                           // underscore
 +
 +    /**
 +     * __construct(): constructor function. Note we document any parameters
 +     *
 +     * @param    string $email email address of the account being accessed
 +     * @param    string $password password of the account being accessed
 +     *
 +     */
 +    public function __construct($email, $password) {
 +        // do stuff here to construct the object. Note that 
 +        // curly braces for functions are on the same line
 +            
 +    }
 +    
 +    /**
 +     * getData(): return data from this object
 +     * 
 +     * @param    string $keyword the keyword in question
 +     * @return    array
 +     *
 +     */
 +    public function getKeywordData($keyword) {
 +        $myArray = array();
 +        // do keyword data lookup and put it into $kwArray
 +        return $myArray;
 +    }
 +}
 +
 +?>
 +
 +</code>