PHP 4.0

1 files changed, 149 insertions, 0 deletions

diff --git a/CODING_STANDARDS b/CODING_STANDARDS
new file mode 100644
index 0000000000..477cad33c9
--- /dev/null
+++ b/CODING_STANDARDS
@@ -0,0 +1,149 @@
+PHP Coding Standards
+====================
+
+
+This file lists several standards that any programmer, adding or changing
+code in PHP, should follow.  Since this file was added at a very late
+stage of the development of PHP v3.0, the code base does not (yet) fully
+follow it, but it's going in that general direction.
+This is an initial version - it'll most probably grow as time passes.
+
+
+Code Implementation
+-------------------
+
+[1] Functions that are given pointers to resources should not free them
+
+For instance, function int mail(char *to, char *from) should NOT free
+to and/or from.
+Exceptions:
+
+  - The function's designated behavior is freeing that resource.  E.g. efree()
+  - The function is given a boolean argument, that controls whether or not
+    the function may free its arguments (if true - the function must free its
+    arguments, if false - it must not)
+  - Low-level parser routines, that are tightly integrated with the token
+    cache and the bison code for minimum memory copying overhead.
+    
+[2] Functions that are tightly integrated with other functions within the
+    same module, and rely on each other non-trivial behavior, should be
+    documented as such and declared 'static'.  They should be avoided if
+    possible.
+
+[3] Use definitions and macros whenever possible, so that constants have
+    meaningful names and can be easily manipulated.  The only exceptions
+    to this rule are 0 and 1, when used as false and true (respectively).
+    Any other use of a numeric constant to specify different behavior
+    or actions should be done through a #define.
+
+[4] When writing functions that deal with strings, be sure to remember
+    that PHP holds the length property of each string, and that it
+    shouldn't be calculated with strlen().  Write your functions in a such
+    a way so that they'll take advantage of the length property, both
+    for efficiency and in order for them to be binary-safe.
+    Functions that change strings and obtain their new lengths while
+    doing so, should return that new length, so it doesn't have to be
+    recalculated with strlen() (e.g. _php3_addslashes())
+
+[5] Use php3_error() to report any errors/warnings during code execution.
+    Use descriptive error messages, and try to avoid using identical
+    error strings for different stages of an error.  For example,
+    if in order to obtain a URL you have to parse the URL, connect,
+    and retreive the text, assuming something can go wrong at each
+    of these stages, don't report an error "Unable to get URL"
+    on all of them, but instead, write something like "Unable
+    to parse URL", "Unable to connect to URL server" and "Unable
+    to fetch URL text", respectively.
+
+[6] NEVER USE strncat().  If you're absolutely sure you know what you're doing,
+    check its man page again, and only then, consider using it, and even then,
+    try avoiding it.
+
+
+Naming Conventions
+------------------
+
+[1] Function names for user functions implementation should be prefixed with
+    "php3_", and followed by a word or an underscore-delimited list of words,
+    in lowercase letters, that describes the function.
+
+[2] Function names used by user functions implementations should be prefixed
+    with "_php3_", and followed by a word or an underscore-delimited list of
+    words, in lowercase letters, that describes the function.  If applicable,
+    they should be declared 'static'.
+    
+[3] Variable names must be meaningful.  One letter variable names must be
+    avoided, except for places where the variable has no real meaning or
+    a trivial meaning (e.g. for (i=0; i<100; i++) ...).
+
+[4] Variable names should be in lowercase;  Use underscores to seperate
+    between words.
+
+
+
+Syntax and indentation
+----------------------
+
+[1] Never use C++ style comments (i.e. // comment).  Always use C-style
+    comments instead.  PHP is written in C, and is aimed at compiling
+    under any ANSI-C compliant compiler.  Even though many compilers
+    accept C++-style comments in C code, you have to ensure that your
+    code would compile with other compilers as well.
+    The only exception to this rule is code that is Win32-specific,
+    because the Win32 port is MS-Visual C++ specific, and this compiler
+    is known to accept C++-style comments in C code.
+
+[2] Use K&R-style.  Of course, we can't and don't want to
+    force anybody to use a style she's not used to, but
+    at the very least, when you write code that goes into the core
+    of PHP or one of its standard modules, please maintain the K&R
+    style.  This applies to just about everything, starting with
+    indentation and comment styles and up to function decleration
+    syntax.
+    
+[3] Be generous with whitespace and braces.  Always prefer
+    if (foo) {
+		bar;
+	}
+	to
+	if(foo)bar;
+	
+    Keep one empty line between the variable decleration section and
+    the statements in a block, as well as between logical statement
+    groups in a block.  Maintain at least one empty line between
+    two functions, preferably two.
+
+Documentation and Folding Hooks
+-------------------------------
+
+In order to make sure that the online documentation stays in line with
+the code, each user-level function should have its user-level function
+prototype before it along with a brief one-line description of what the
+function does.  It would look like this:
+
+/* {{{ proto int abs(int number)
+   Return the absolute value of the number */
+void php3_abs(INTERNAL_FUNCTION_PARAMETERS) {
+   ...
+}
+/* }}} */
+
+The {{{ symbols are the default folding symbols for the folding mode in
+Emacs.  vim will soon have support for folding as well.  Folding is very
+useful when dealing with large files because you can scroll through the 
+file quickly and just unfold the function you wish to work on.  The }}}
+at the end of each function marks the end of the fold, and should be on
+a separate line.
+
+The "proto" keyword there is just a helper for the doc/genfuncsummary script
+which generates a full function summary.  Having this keyword in front of the
+function prototypes allows us to put folds elsewhere in the code without
+messing up the function summary.
+
+Optional arguments are written like this:
+
+/* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
+
+And yes, please keep everything on a single line, even if that line is massive.
+
+