mirror of
https://github.com/php/php-src.git
synced 2024-09-21 18:07:23 +00:00
150 lines
6.2 KiB
Plaintext
150 lines
6.2 KiB
Plaintext
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.
|
|
|
|
|