Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 149 lines (114 sloc) 6.219 kb
aceaabc @zsuraski PHP 4.0
zsuraski authored
1 PHP Coding Standards
2 ====================
3
4
5 This file lists several standards that any programmer, adding or changing
6 code in PHP, should follow. Since this file was added at a very late
7 stage of the development of PHP v3.0, the code base does not (yet) fully
8 follow it, but it's going in that general direction.
9 This is an initial version - it'll most probably grow as time passes.
10
11
12 Code Implementation
13 -------------------
14
15 [1] Functions that are given pointers to resources should not free them
16
17 For instance, function int mail(char *to, char *from) should NOT free
18 to and/or from.
19 Exceptions:
20
21 - The function's designated behavior is freeing that resource. E.g. efree()
22 - The function is given a boolean argument, that controls whether or not
23 the function may free its arguments (if true - the function must free its
24 arguments, if false - it must not)
25 - Low-level parser routines, that are tightly integrated with the token
26 cache and the bison code for minimum memory copying overhead.
27
28 [2] Functions that are tightly integrated with other functions within the
29 same module, and rely on each other non-trivial behavior, should be
30 documented as such and declared 'static'. They should be avoided if
31 possible.
32
33 [3] Use definitions and macros whenever possible, so that constants have
34 meaningful names and can be easily manipulated. The only exceptions
35 to this rule are 0 and 1, when used as false and true (respectively).
36 Any other use of a numeric constant to specify different behavior
37 or actions should be done through a #define.
38
39 [4] When writing functions that deal with strings, be sure to remember
40 that PHP holds the length property of each string, and that it
41 shouldn't be calculated with strlen(). Write your functions in a such
42 a way so that they'll take advantage of the length property, both
43 for efficiency and in order for them to be binary-safe.
44 Functions that change strings and obtain their new lengths while
45 doing so, should return that new length, so it doesn't have to be
585e338 php4ize a bit.
Sterling Hughes authored
46 recalculated with strlen() (e.g. php_addslashes())
aceaabc @zsuraski PHP 4.0
zsuraski authored
47
585e338 php4ize a bit.
Sterling Hughes authored
48 [5] Use php_error() to report any errors/warnings during code execution.
aceaabc @zsuraski PHP 4.0
zsuraski authored
49 Use descriptive error messages, and try to avoid using identical
50 error strings for different stages of an error. For example,
51 if in order to obtain a URL you have to parse the URL, connect,
52 and retreive the text, assuming something can go wrong at each
53 of these stages, don't report an error "Unable to get URL"
54 on all of them, but instead, write something like "Unable
55 to parse URL", "Unable to connect to URL server" and "Unable
56 to fetch URL text", respectively.
57
58 [6] NEVER USE strncat(). If you're absolutely sure you know what you're doing,
59 check its man page again, and only then, consider using it, and even then,
60 try avoiding it.
61
62
63 Naming Conventions
64 ------------------
65
585e338 php4ize a bit.
Sterling Hughes authored
66 [1] Function names for user functions should be enclosed with in
67 the PHP_FUNCTION() macro.
aceaabc @zsuraski PHP 4.0
zsuraski authored
68
585e338 php4ize a bit.
Sterling Hughes authored
69 [2] Function names used by user functions should be prefixed
70 with "_php_", and followed by a word or an underscore-delimited list of
aceaabc @zsuraski PHP 4.0
zsuraski authored
71 words, in lowercase letters, that describes the function. If applicable,
72 they should be declared 'static'.
73
74 [3] Variable names must be meaningful. One letter variable names must be
75 avoided, except for places where the variable has no real meaning or
76 a trivial meaning (e.g. for (i=0; i<100; i++) ...).
77
78 [4] Variable names should be in lowercase; Use underscores to seperate
79 between words.
80
81
82 Syntax and indentation
83 ----------------------
84
85 [1] Never use C++ style comments (i.e. // comment). Always use C-style
86 comments instead. PHP is written in C, and is aimed at compiling
87 under any ANSI-C compliant compiler. Even though many compilers
88 accept C++-style comments in C code, you have to ensure that your
89 code would compile with other compilers as well.
90 The only exception to this rule is code that is Win32-specific,
91 because the Win32 port is MS-Visual C++ specific, and this compiler
92 is known to accept C++-style comments in C code.
93
94 [2] Use K&R-style. Of course, we can't and don't want to
95 force anybody to use a style she's not used to, but
96 at the very least, when you write code that goes into the core
97 of PHP or one of its standard modules, please maintain the K&R
98 style. This applies to just about everything, starting with
99 indentation and comment styles and up to function decleration
100 syntax.
101
102 [3] Be generous with whitespace and braces. Always prefer
103 if (foo) {
104 bar;
105 }
106 to
107 if(foo)bar;
108
109 Keep one empty line between the variable decleration section and
110 the statements in a block, as well as between logical statement
111 groups in a block. Maintain at least one empty line between
112 two functions, preferably two.
113
114 Documentation and Folding Hooks
115 -------------------------------
116
117 In order to make sure that the online documentation stays in line with
118 the code, each user-level function should have its user-level function
119 prototype before it along with a brief one-line description of what the
120 function does. It would look like this:
121
122 /* {{{ proto int abs(int number)
123 Return the absolute value of the number */
585e338 php4ize a bit.
Sterling Hughes authored
124 PHP_FUNCTION(abs)
125 {
aceaabc @zsuraski PHP 4.0
zsuraski authored
126 ...
127 }
128 /* }}} */
129
130 The {{{ symbols are the default folding symbols for the folding mode in
131 Emacs. vim will soon have support for folding as well. Folding is very
132 useful when dealing with large files because you can scroll through the
133 file quickly and just unfold the function you wish to work on. The }}}
134 at the end of each function marks the end of the fold, and should be on
135 a separate line.
136
137 The "proto" keyword there is just a helper for the doc/genfuncsummary script
138 which generates a full function summary. Having this keyword in front of the
139 function prototypes allows us to put folds elsewhere in the code without
140 messing up the function summary.
141
142 Optional arguments are written like this:
143
144 /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
145
146 And yes, please keep everything on a single line, even if that line is massive.
147
148
Something went wrong with that request. Please try again.