home *** CD-ROM | disk | FTP | other *** search
/ PC World 2001 August / PCWorld_2001-08_cd.bin / Komunikace / phptriad / phptriadsetup2-11.exe / php / pear / CODING_STANDARDS < prev    next >
Lisp/Scheme  |  2001-02-18  |  8KB  |  239 lines
  1. ===========================================================================
  2. || PEAR Coding Standards                                                 ||
  3. ===========================================================================
  4.  
  5. $Id: CODING_STANDARDS,v 1.5 2001/02/18 17:47:43 jon Exp $
  6.  
  7. -------------
  8. [1] Indenting
  9. =============
  10.  
  11. Use an indent of 4 spaces, with no tabs. If you use Emacs to edit PEAR
  12. code, you should set indent-tabs-mode to nil. Here is an example mode
  13. hook that will set up Emacs according to these guidelines (you will
  14. need to ensure that it is called when you are editing php files):
  15.  
  16. (defun php-mode-hook ()
  17.   (setq tab-width 4
  18.         c-basic-offset 4
  19.         c-hanging-comment-ender-p nil
  20.         indent-tabs-mode nil))
  21.  
  22. Here are vim rules for the same thing:
  23.  
  24.   set expandtab 
  25.   set shiftwidth=4 
  26.   set tabstop=4 
  27.  
  28.  
  29. ----------------------
  30. [2] Control Structures
  31. ======================
  32.  
  33. These include if, for, while, switch, etc. Here is an example if statement,
  34. since it is the most complicated of them:
  35.  
  36.   if ((condition1) || (condition2)) {
  37.       action1;
  38.   } elseif ((condition3) && (condition4)) {
  39.       action2;
  40.   } else {
  41.       defaultaction;
  42.   }
  43.  
  44. Control statements should have one space between the control keyword
  45. and opening parenthesis, to distinguish them from function calls.
  46.  
  47. You are strongly encouraged to always use curly braces even in
  48. situations where they are technically optional. Having them increases
  49. readability and decreases the likelihood of logic errors being
  50. introduced when new lines are added.
  51.  
  52. For switch statements:
  53.  
  54.   switch (condition) {
  55.   case 1:
  56.       action1;
  57.       break;
  58.  
  59.   case 2:
  60.       action2;
  61.       break;
  62.  
  63.   default:
  64.       defaultaction;
  65.       break;
  66.  
  67.   }
  68.  
  69.  
  70. ------------------
  71. [3] Function Calls
  72. ==================
  73.  
  74. Functions should be called with no spaces between the function name,
  75. the opening parenthesis, and the first parameter; spaces between commas
  76. and each parameter, and no space between the last parameter, the
  77. closing parenthesis, and the semicolon. Here's an example:
  78.  
  79.   $var = foo($bar, $baz, $quux);
  80.  
  81. As displayed above, there should be one space on either side of an
  82. equals sign used to assign the return value of a function to a
  83. variable. In the case of a block of related assignments, more space
  84. may be inserted to promote readability:
  85.  
  86.   $short         = foo($bar);
  87.   $long_variable = foo($baz);
  88.  
  89.  
  90. ------------------------
  91. [4] Function Definitions
  92. ========================
  93.  
  94. Function declaractions follow the "one true brace" convention:
  95.  
  96. function fooFunction($arg1, $arg2 = '')
  97. {
  98.     if (condition) {
  99.         statement;
  100.     }
  101.     return $val;
  102. }
  103.  
  104. Arguments with default values go at the end of the argument list.
  105. Always attempt to return a meaningful value from a function if one is
  106. appropriate. Here is a slightly longer example:
  107.  
  108. function connect(&$dsn, $persistent = false)
  109. {
  110.     if (is_array($dsn)) {
  111.         $dsninfo = &$dsn;
  112.     } else {
  113.         $dsninfo = DB::parseDSN($dsn);
  114.     }
  115.     
  116.     if (!$dsninfo || !$dsninfo['phptype']) {
  117.         return $this->raiseError();
  118.     }
  119.     
  120.     return true;
  121. }
  122.  
  123.  
  124. ------------
  125. [5] Comments
  126. ============
  127.  
  128. Inline documentation for classes should follow the PHPDoc convention, similar 
  129. to Javadoc. More information about PHPDoc can be found here:
  130.  
  131.     http://www.phpdoc.de/
  132.  
  133. Non-documentation comments are strongly encouraged. A general rule of
  134. thumb is that if you look at a section of code and think "Wow, I don't
  135. want to try and describe that", you need to comment it before you
  136. forget how it works.
  137.  
  138. C++ style comments (/* */) and standard C comments (// ) are both
  139. fine. Use of perl/shell style comments (# ) is discouraged.
  140.  
  141.  
  142. ------------------
  143. [6] Including Code
  144. ==================
  145.  
  146. Anywhere you are unconditionally including a class file, use
  147. require_once. Anywhere you are conditionally including a class file
  148. (for example, factory methods), use include_once. Either of these will
  149. ensure that class files are included only once. They share the same
  150. file list, so you don't need to worry about mixing them - a file
  151. included with require_once will not be included again by include_once.
  152.  
  153. Note: include_once and require_once are statements, not functions. You
  154. don't need parentheses around the filename to be included.
  155.  
  156.  
  157. -----------------
  158. [7] PHP Code Tags
  159. =================
  160.  
  161. ALWAYS use <?php ?> to delimit PHP code, not the <? ?> shorthand.
  162. This is required for PEAR compliance and is also the most portable way
  163. to include PHP code on differing operating systems and setups.
  164.  
  165.  
  166. -------------------------
  167. [8] Header Comment Blocks
  168. =========================
  169.  
  170. All source code files in the core PEAR distribution should contain the
  171. following comment block as the header:
  172.  
  173. /* vim: set expandtab tabstop=4 shiftwidth=4: */
  174. // +----------------------------------------------------------------------+
  175. // | PHP version 4.0                                                      |
  176. // +----------------------------------------------------------------------+
  177. // | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group             |
  178. // +----------------------------------------------------------------------+
  179. // | This source file is subject to version 2.0 of the PHP license,       |
  180. // | that is bundled with this package in the file LICENSE, and is        |
  181. // | available at through the world-wide-web at                           |
  182. // | http://www.php.net/license/2_02.txt.                                 |
  183. // | If you did not receive a copy of the PHP license and are unable to   |
  184. // | obtain it through the world-wide-web, please send a note to          |
  185. // | license@php.net so we can mail you a copy immediately.               |
  186. // +----------------------------------------------------------------------+
  187. // | Authors: Original Author <author@example.com>                        |
  188. // |          Your Name <you@example.com>                                 |
  189. // +----------------------------------------------------------------------+
  190. //
  191. // $Id: CODING_STANDARDS,v 1.5 2001/02/18 17:47:43 jon Exp $
  192.  
  193. There's no hard rule to determine when a new code contributer should be
  194. added to the list of authors for a given source file.  In general, their
  195. changes should fall into the "substantial" category (meaning somewhere
  196. around 10% to 20% of code changes).  Exceptions could be made for rewriting
  197. functions or contributing new logic.
  198.  
  199. Simple code reorganization or bug fixes would not justify the addition of a
  200. new individual to the list of authors.
  201.  
  202. Files not in the core PEAR repository should have a similar block
  203. stating the copyright, the license, and the authors. All files should
  204. include the modeline comments to encourage consistency.
  205.  
  206.  
  207. ------------
  208. [9] CVS Tags
  209. ============
  210.  
  211. Include the <dollar>Id CVS vendor tag in each file.  As each
  212. file is edited, add this tag if it's not yet present (or replace existing
  213. forms such as "Last Modified:", etc.).
  214.  
  215. [NOTE: we have a custom $Horde tag in Horde cvs to track our versions 
  216. seperately; we could do the same and make a $PEAR tag, that would remain even 
  217. if PEAR files were put into another source control system, etc...]
  218.  
  219.  
  220. -----------------
  221. [10] Example URLs
  222. =================
  223.  
  224. Use "example.com" for all example URLs, per RFC 2606.
  225.  
  226.  
  227. ---------------------
  228. [11] Naming Constants
  229. =====================
  230.  
  231. Constants should always be uppercase, with underscores to seperate
  232. words. Prefix constant names with the name of the class/package they
  233. are used in. For example, the constants used by the DB:: package all
  234. begin with "DB_".
  235.  
  236. True and false are built in to the php language and behave like
  237. constants, but should be written in lowercase to distinguish them from
  238. user-defined constants.
  239.