Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 221 lines (172 sloc) 9.014 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
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
8 follow it, but it's going in that general direction. Since we are now
9 well into the version 4 releases, many sections have been recoded to use
10 these rules.
aceaabc @zsuraski PHP 4.0
zsuraski authored
11
12
13 Code Implementation
14 -------------------
15
16 [1] Functions that are given pointers to resources should not free them
17
18 For instance, function int mail(char *to, char *from) should NOT free
19 to and/or from.
20 Exceptions:
21
22 - The function's designated behavior is freeing that resource. E.g. efree()
23 - The function is given a boolean argument, that controls whether or not
24 the function may free its arguments (if true - the function must free its
25 arguments, if false - it must not)
26 - Low-level parser routines, that are tightly integrated with the token
27 cache and the bison code for minimum memory copying overhead.
28
29 [2] Functions that are tightly integrated with other functions within the
30 same module, and rely on each other non-trivial behavior, should be
31 documented as such and declared 'static'. They should be avoided if
32 possible.
33
34 [3] Use definitions and macros whenever possible, so that constants have
35 meaningful names and can be easily manipulated. The only exceptions
36 to this rule are 0 and 1, when used as false and true (respectively).
37 Any other use of a numeric constant to specify different behavior
38 or actions should be done through a #define.
39
40 [4] When writing functions that deal with strings, be sure to remember
41 that PHP holds the length property of each string, and that it
42 shouldn't be calculated with strlen(). Write your functions in a such
43 a way so that they'll take advantage of the length property, both
44 for efficiency and in order for them to be binary-safe.
45 Functions that change strings and obtain their new lengths while
46 doing so, should return that new length, so it doesn't have to be
585e338 php4ize a bit.
Sterling Hughes authored
47 recalculated with strlen() (e.g. php_addslashes())
aceaabc @zsuraski PHP 4.0
zsuraski authored
48
585e338 php4ize a bit.
Sterling Hughes authored
49 [5] Use php_error() to report any errors/warnings during code execution.
aceaabc @zsuraski PHP 4.0
zsuraski authored
50 Use descriptive error messages, and try to avoid using identical
51 error strings for different stages of an error. For example,
52 if in order to obtain a URL you have to parse the URL, connect,
53 and retreive the text, assuming something can go wrong at each
54 of these stages, don't report an error "Unable to get URL"
55 on all of them, but instead, write something like "Unable
56 to parse URL", "Unable to connect to URL server" and "Unable
57 to fetch URL text", respectively.
58
59 [6] NEVER USE strncat(). If you're absolutely sure you know what you're doing,
60 check its man page again, and only then, consider using it, and even then,
61 try avoiding it.
62
63
64 Naming Conventions
65 ------------------
66
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
67 [1] Function names for user-level functions should be enclosed with in
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
68 the PHP_FUNCTION() macro. They should be in lowercase, with words
69 underscore delimited, with care taken to minimize the letter count.
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
70 Abbreviations should not be used when they greatly decrease the
71 readability of the function name itself.
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
72
73 Good:
74 'mcrypt_enc_self_test'
75 'mysql_list_fields'
76
77 Ok:
78 'mcrypt_module_get_algo_supported_key_sizes'
79 (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
80 'get_html_translation_table'
81 (could be 'html_get_trans_table'?)
82
83 Bad:
84 'hw_GetObjectByQueryCollObj'
85 'pg_setclientencoding'
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
86 'jf_n_s_i'
87
88
89 [2] If they are part of a "parent set" of functions, that parent should
90 be included in the user function name, and should be clearly related
91 to the parent program or function family. This should be in the form
92 of parent_*.
93
94 A family of 'foo' functions, for example:
95 Good:
96 'foo_select_bar'
97 'foo_insert_baz'
98 'foo_delete_baz'
aceaabc @zsuraski PHP 4.0
zsuraski authored
99
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
100 Bad:
101 'fooselect_bar'
102 'fooinsertbaz'
103 'delete_foo_baz'
104
105 [3] Function names used by user functions should be prefixed
585e338 php4ize a bit.
Sterling Hughes authored
106 with "_php_", and followed by a word or an underscore-delimited list of
aceaabc @zsuraski PHP 4.0
zsuraski authored
107 words, in lowercase letters, that describes the function. If applicable,
108 they should be declared 'static'.
109
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
110 [4] Variable names must be meaningful. One letter variable names must be
aceaabc @zsuraski PHP 4.0
zsuraski authored
111 avoided, except for places where the variable has no real meaning or
112 a trivial meaning (e.g. for (i=0; i<100; i++) ...).
113
8a5402c Fixed some spelling errors.
Egon Schmid authored
114 [5] Variable names should be in lowercase. Use underscores to separate
aceaabc @zsuraski PHP 4.0
zsuraski authored
115 between words.
116
117
118 Syntax and indentation
119 ----------------------
120
121 [1] Never use C++ style comments (i.e. // comment). Always use C-style
122 comments instead. PHP is written in C, and is aimed at compiling
123 under any ANSI-C compliant compiler. Even though many compilers
124 accept C++-style comments in C code, you have to ensure that your
125 code would compile with other compilers as well.
126 The only exception to this rule is code that is Win32-specific,
127 because the Win32 port is MS-Visual C++ specific, and this compiler
128 is known to accept C++-style comments in C code.
129
130 [2] Use K&R-style. Of course, we can't and don't want to
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
131 force anybody to use a style he or she is not used to, but,
aceaabc @zsuraski PHP 4.0
zsuraski authored
132 at the very least, when you write code that goes into the core
133 of PHP or one of its standard modules, please maintain the K&R
134 style. This applies to just about everything, starting with
8a5402c Fixed some spelling errors.
Egon Schmid authored
135 indentation and comment styles and up to function declaration
aceaabc @zsuraski PHP 4.0
zsuraski authored
136 syntax.
7d220af small clarification
Hartmut Holzgraefe authored
137
138 (see also http://www.tuxedo.org/~esr/jargon/html/entry/indent-style.html)
aceaabc @zsuraski PHP 4.0
zsuraski authored
139
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
140 [3] Be generous with whitespace and braces. Always prefer:
141
142 if (foo) {
aceaabc @zsuraski PHP 4.0
zsuraski authored
143 bar;
144 }
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
145
146 to:
147
aceaabc @zsuraski PHP 4.0
zsuraski authored
148 if(foo)bar;
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
149
8a5402c Fixed some spelling errors.
Egon Schmid authored
150 Keep one empty line between the variable declaration section and
aceaabc @zsuraski PHP 4.0
zsuraski authored
151 the statements in a block, as well as between logical statement
152 groups in a block. Maintain at least one empty line between
153 two functions, preferably two.
154
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
155 [4] When indenting, use the tab character. A tab is expected to represent
156 four spaces. It is important to maintain consistency in indenture so
157 that definitions, comments, and control structures line up correctly.
158
aceaabc @zsuraski PHP 4.0
zsuraski authored
159 Documentation and Folding Hooks
160 -------------------------------
161
162 In order to make sure that the online documentation stays in line with
163 the code, each user-level function should have its user-level function
164 prototype before it along with a brief one-line description of what the
165 function does. It would look like this:
166
167 /* {{{ proto int abs(int number)
8a5402c Fixed some spelling errors.
Egon Schmid authored
168 Returns the absolute value of the number */
585e338 php4ize a bit.
Sterling Hughes authored
169 PHP_FUNCTION(abs)
170 {
aceaabc @zsuraski PHP 4.0
zsuraski authored
171 ...
172 }
173 /* }}} */
174
175 The {{{ symbols are the default folding symbols for the folding mode in
25c3a3a @rlerdorf vim-6 does folding - clean up a bunch of missing folding tags plus
rlerdorf authored
176 Emacs and vim (set fdm=marker). Folding is very useful when dealing with
177 large files because you can scroll through the file quickly and just unfold
178 the function you wish to work on. The }}} at the end of each function marks
179 the end of the fold, and should be on a separate line.
aceaabc @zsuraski PHP 4.0
zsuraski authored
180
181 The "proto" keyword there is just a helper for the doc/genfuncsummary script
182 which generates a full function summary. Having this keyword in front of the
183 function prototypes allows us to put folds elsewhere in the code without
184 messing up the function summary.
185
186 Optional arguments are written like this:
187
188 /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
8a5402c Fixed some spelling errors.
Egon Schmid authored
189 Returns a header object with the defined parameters */
aceaabc @zsuraski PHP 4.0
zsuraski authored
190
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
191 And yes, please keep the prototype on a single line, even if that line
192 is massive.
193
194 New and Experimental Functions
195 -----------------------------------
196 To reduce the problems normally associated with the first public
197 implementation of a new set of functions, it has been suggested
198 that the first implementation include a file labeled 'EXPERIMENTAL'
199 in the function directory, and that the functions follow the
200 standard prefixing conventions during their initial implementation.
201
202 The file labelled 'EXPERIMENTAL' should include the following
203 information:
8a5402c Fixed some spelling errors.
Egon Schmid authored
204 Any authoring information (known bugs, future directions of the module).
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
205 Ongoing status notes which may not be appropriate for CVS comments.
aceaabc @zsuraski PHP 4.0
zsuraski authored
206
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
207 Aliases & Legacy Documentation
208 -----------------------------------
209 You may also have some deprecated aliases with close to duplicate
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
210 names, for example, somedb_select_result and somedb_selectresult. For
8a5402c Fixed some spelling errors.
Egon Schmid authored
211 documentation purposes, these will only be documented by the most
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
212 current name, with the aliases listed in the documentation for
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
213 the parent function. For ease of reference, user-functions with
214 completely different names, that alias to the same function (such as
215 highlight_file and show_source), will be separately documented. The
216 proto should still be included, describing which function is aliased.
217
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
218 Backwards compatible functions and names should be maintained as long
219 as the code can be reasonably be kept as part of the codebase. See
8a5402c Fixed some spelling errors.
Egon Schmid authored
220 /phpdoc/README for more information on documentation.
Something went wrong with that request. Please try again.