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
processes:code-documentation-standards [May 9, 2009 11:02 PM]
dordal 		processes:code-documentation-standards [Oct 20, 2023 08:43 PM]
135.181.114.235 old revision restored (Oct 20, 2023 12:07 PM)
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>