Last Updated: 20 Oct 2023
|
Differences
This shows you the differences between two versions of the page.
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:// | ||
+ | |||
+ | For the code itself, I try to follow the [[http:// | ||
+ | * Lines should be 75-85 characters long, no more. Four spaces should be used for indentation, | ||
+ | * One class per file. | ||
+ | * Underscores in class names map to directory separators (e.g. '' | ||
+ | * 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. '' | ||
+ | |||
+ | For a great overview of code+documentation best practices in PHP (as well as other PHP best practices), see Matthew Weier O' | ||
+ | |||
+ | 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 '' | ||
+ | |||
+ | <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 = ' | ||
+ | const AW_COUNTRIES = ' | ||
+ | | ||
+ | public $setupList = null; // variables are declared in camelCase | ||
+ | private $_apiSoapClient = null; // and private/ | ||
+ | // underscore | ||
+ | |||
+ | /** | ||
+ | * __construct(): | ||
+ | * | ||
+ | * @param | ||
+ | * @param | ||
+ | * | ||
+ | */ | ||
+ | public function __construct($email, | ||
+ | // 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 | ||
+ | * @return | ||
+ | * | ||
+ | */ | ||
+ | public function getKeywordData($keyword) { | ||
+ | $myArray = array(); | ||
+ | // do keyword data lookup and put it into $kwArray | ||
+ | return $myArray; | ||
+ | } | ||
+ | } | ||
+ | |||
+ | ?> | ||
+ | |||
+ | </ |