initial coding standards doc for all to argue over.

26 years ago · 4fe3182b1f
1 changed files with 238 additions and 0 deletions
--- a/pear/CODING_STANDARDS
+++ b/pear/CODING_STANDARDS
@ -0,0 +1,238 @@
+===========================================================================
+|| PEAR Coding Standards                                                 ||
+===========================================================================
+
+$Id$
+
+-------------
+[1] Indenting
+=============
+
+Use an indent of 4 spaces, with no tabs. If you use Emacs to edit PEAR
+code, you should set indent-tabs-mode to nil. Here is an example mode
+hook that will set up Emacs according to these guidelines (you will
+need to ensure that it is called when you are editing php files):
+
+(defun php-mode-hook ()
+  (setq tab-width 4
+        c-basic-offset 4
+        c-hanging-comment-ender-p nil
+        indent-tabs-mode nil))
+
+Here are vim rules for the same thing:
+
+  set expandtab 
+  set shiftwidth=4 
+  set tabstop=4 
+
+
+----------------------
+[2] Control Structures
+======================
+
+These include if, for, while, switch, etc. Here is an example if statement,
+since it is the most complicated of them:
+
+  if ((condition1) || (condition2)) {
+      action1;
+  } elseif ((condition3) && (condition4)) {
+      action2;
+  } else {
+      defaultaction;
+  }
+
+Control statements should have one space between the control keyword
+and opening parenthesis, to distinguish them from function calls.
+
+You are strongly encouraged to always use curly braces even in
+situations where they are technically optional. Having them increases
+readability and decreases the likelihood of logic errors being
+introduced when new lines are added.
+
+For switch statements:
+
+  switch (condition) {
+  case 1:
+      action1;
+      break;
+
+  case 2:
+      action2;
+      break;
+
+  default:
+      defaultaction;
+      break;
+
+  }
+
+
+------------------
+[3] Function Calls
+==================
+
+Functions should be called with no spaces between the function name,
+the opening parenthesis, and the first parameter; spaces between commas
+and each parameter, and no space between the last parameter, the
+closing parenthesis, and the semicolon. Here's an example:
+
+  $var = foo($bar, $baz, $quux);
+
+As displayed above, there should be one space on either side of an
+equals sign used to assign the return value of a function to a
+variable. In the case of a block of related assignments, more space
+may be inserted to promote readability:
+
+  $short         = foo($bar);
+  $long_variable = foo($baz);
+
+
+------------------------
+[4] Function Definitions
+========================
+
+Function declaractions follow the "one true brace" convention:
+
+function fooFunction($arg1, $arg2 = '')
+{
+    if (condition) {
+        statement;
+    }
+    return $val;
+}
+
+Arguments with default values go at the end of the argument list.
+Always attempt to return a meaningful value from a function if one is
+appropriate. Here is a slightly longer example:
+
+function connect(&$dsn, $persistent = false)
+{
+    if (is_array($dsn)) {
+        $dsninfo = &$dsn;
+    } else {
+        $dsninfo = DB::parseDSN($dsn);
+    }
+    
+    if (!$dsninfo || !$dsninfo['phptype']) {
+        return $this->raiseError();
+    }
+    
+    return true;
+}
+
+
+------------
+[5] Comments
+============
+
+Inline documentation for classes should follow the PHPDoc convention, similar 
+to Javadoc. More information about PHPDoc can be found here:
+
+    http://www.phpdoc.de/
+
+Non-documentation comments are strongly encouraged. A general rule of
+thumb is that if you look at a section of code and think "Wow, I don't
+want to try and describe that", you need to comment it before you
+forget how it works.
+
+C++ style comments (/* */) and standard C comments (// ) are both
+fine. Use of perl/shell style comments (# ) is discouraged.
+
+
+------------------
+[6] Including Code
+==================
+
+Anywhere you are unconditionally including a class file, use
+require_once. Anywhere you are conditionally including a class file
+(for example, factory methods), use include_once. Either of these will
+ensure that class files are included only once. They share the same
+file list, so you don't need to worry about mixing them - a file
+included with require_once will not be included again by include_once.
+
+Note: include_once and require_once are statements, not functions. You
+don't need parentheses around the filename to be included.
+
+
+-----------------
+[7] PHP Code Tags
+=================
+
+ALWAYS use <?php ?> to delimit PHP code, not the <? ?> shorthand.
+This is required for PEAR compliance and is also the most portable way
+to include PHP code on differing operating systems and setups.
+
+
+-------------------------
+[8] Header Comment Blocks
+=========================
+
+All source code files in the core PEAR distribution should contain the
+following comment block as the header:
+
+/* vim: set ts=4 sw=4: */
+// +----------------------------------------------------------------------+
+// | PHP version 4.0                                                      |
+// +----------------------------------------------------------------------+
+// | Copyright (c) 1997, 1998, 1999, 2000 The PHP Group                   |
+// +----------------------------------------------------------------------+
+// | This source file is subject to version 2.0 of the PHP license,       |
+// | that is bundled with this package in the file LICENSE, and is        |
+// | available at through the world-wide-web at                           |
+// | http://www.php.net/license/2_02.txt.                                 |
+// | If you did not receive a copy of the PHP license and are unable to   |
+// | obtain it through the world-wide-web, please send a note to          |
+// | license@php.net so we can mail you a copy immediately.               |
+// +----------------------------------------------------------------------+
+// | Authors: Original Author <author@example.com>                        |
+// |          Your Name <you@example.com>                                 |
+// +----------------------------------------------------------------------+
+//
+// $Id$
+
+There's no hard rule to determine when a new code contributer should be
+added to the list of authors for a given source file.  In general, their
+changes should fall into the "substantial" category (meaning somewhere
+around 10% to 20% of code changes).  Exceptions could be made for rewriting
+functions or contributing new logic.
+
+Simple code reorganization or bug fixes would not justify the addition of a
+new individual to the list of authors.
+
+Files not in the core PEAR repository should have a similar block
+stating the copyright, the license, and the authors. All files should
+include the modeline comments to encourage consistency.
+
+
+------------
+[9] CVS Tags
+============
+
+Include the <dollar>Id CVS vendor tag in each file.  As each
+file is edited, add this tag if it's not yet present (or replace existing
+forms such as "Last Modified:", etc.).
+
+[NOTE: we have a custom $Horde tag in Horde cvs to track our versions 
+seperately; we could do the same and make a $PEAR tag, that would remain even 
+if PEAR files were put into another source control system, etc...]
+
+
+-----------------
+[10] Example URLs
+=================
+
+Use "example.com" for all example URLs, per RFC 2606.
+
+
+---------------------
+[11] Naming Constants
+=====================
+
+Constants should always be uppercase, with underscores to seperate
+words. Prefix constant names with the name of the class/package they
+are used in. For example, the constants used by the DB:: package all
+begin with "DB_".
+
+True and false are built in to the php language and behave like
+constants, but should be written in lowercase to distinguish them from
+user-defined constants.