| commit | author | age | ||
| b64955 | 1 | Some guidelines for web development with php. |
| P | 2 | ----------------------------------------------------- |
| 3 | Unix Line Breaks Only, NO windows breaks please. | |
| 4 | ||
| 5 | Tabs set at 4 spaces either as tabs or spaces. | |
| 6 | ||
| 7 | Pear coding guiidelines | |
| 8 | ||
| 9 | //***************************************************************************** | |
| 10 | // Commenting style | |
| 11 | //***************************************************************************** | |
| 12 | phpdoc is used for creating and autogenerating the documentation, this means that | |
| 13 | some of the comments can be formatted to be included in documentation. | |
| 14 | ie the source files are scanned then processed and html docs are created. | |
| 15 | ||
| 16 | The comments break down into the following types | |
| 17 | // is uses for removing lines and debug dev etc | |
| 18 | //** and //* are used as "sub comments" | |
| 19 | /* | |
| 20 | is used to comment out blocks | |
| 21 | */ | |
| 22 | /** is used to create documentaion | |
| 23 | * thats over | |
| 24 | * lines | |
| 25 | */ | |
| 26 | ||
| 27 | If you need to block out a section then use | |
| 28 | /* | |
| 29 | function redundant_code(){ | |
| 30 | something here | |
| 31 | } | |
| 32 | */ | |
| 33 | ||
| 34 | To block out single lines use // and all // are assumed to be redundant test code and NOT comments | |
| 35 | ||
| 36 | // print_r($foo); | |
| 37 | ||
| 38 | For incline comment use //** and //* eg | |
| 39 | ||
| 40 | //** Decide what do do | |
| 41 | switch($decide){ | |
| 42 | //* blow it up | |
| 43 | case 'baloon': | |
| 44 | $foo->gas(+1); | |
| 45 | // test_pressure(); << inline comment | |
| 46 | break; | |
| 47 | ||
| 48 | //* Do default action | |
| 49 | default: | |
| 50 | do_land(); | |
| 51 | get_gps(); | |
| 52 | //* following grant greaceful exit | |
| 53 | //basket_exit_crash(); | |
| 54 | basket_exit(); | |
| 55 | ||
| 56 | } | |
| 57 | ||
| 58 | Do not use the phpdoc on every function, eg | |
| 59 | ||
| 60 | /** | |
| 61 | * Login an user | |
| 62 | * @param string user username | |
| 63 | * @param string password of user | |
| 64 | */ | |
| 65 | >> | |
| 66 | function login($user, $pass){ | |
| 67 | ....... | |
| 68 | } | |
| 69 | << | |
| 70 | as this function explains its self, the followinf clean code will suffice | |
| 71 | >> | |
| 72 | function login($user, $pass){ | |
| 73 | ....... | |
| 74 | } | |
| 75 | ||
| 76 | If you do need to explain a function then put un the summary syntax eg | |
| 77 | ||
| 78 | /** Pass an array of values where third param is bar | |
| 79 | * $foo['bar'] = 1; // allow an user | |
| 80 | * $foo['bar'] = 2; // destroy user | |
| 81 | * $foo['bar'] = -1; // recreate | |
| 82 | */ | |
| 83 | public function do_something($x, $y, $foo){ | |
| 84 | ... do something interesting | |
| 85 | } | |
| 86 | ||
| 87 | ||
| 88 | ||
