diff options
Diffstat (limited to 'CODING_STANDARDS')
| -rw-r--r-- | CODING_STANDARDS | 149 |
1 files changed, 0 insertions, 149 deletions
diff --git a/CODING_STANDARDS b/CODING_STANDARDS deleted file mode 100644 index 477cad33c9..0000000000 --- a/CODING_STANDARDS +++ /dev/null @@ -1,149 +0,0 @@ -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. - - |