summaryrefslogtreecommitdiff
path: root/CODING_STANDARDS
diff options
context:
space:
mode:
authorZeev Suraski <zeev@php.net>1999-04-07 21:05:13 (GMT)
committerZeev Suraski <zeev@php.net>1999-04-07 21:05:13 (GMT)
commitaceaabceffd537a0ed83fa25e189b08eae585f4a (patch)
treebcef55f16a2ae57c1c883b34347f9e6906ca6dfe /CODING_STANDARDS
parentd94f3e22ae6fe17d82b189dc362e975a906f919a (diff)
downloadphp-aceaabceffd537a0ed83fa25e189b08eae585f4a.tar.gz
PHP 4.0
Diffstat (limited to 'CODING_STANDARDS')
-rw-r--r--CODING_STANDARDS149
1 files changed, 149 insertions, 0 deletions
diff --git a/CODING_STANDARDS b/CODING_STANDARDS
new file mode 100644
index 0000000..477cad3
--- /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.
+
+