Skip to content
Newer
Older
100644 220 lines (172 sloc) 8.74 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
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
114 [5] Variable names should be in lowercase; Use underscores to seperate
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
135 indentation and comment styles and up to function decleration
136 syntax.
137
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
138 [3] Be generous with whitespace and braces. Always prefer:
139
140 if (foo) {
aceaabc @zsuraski PHP 4.0
zsuraski authored
141 bar;
142 }
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
143
144 to:
145
aceaabc @zsuraski PHP 4.0
zsuraski authored
146 if(foo)bar;
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
147
aceaabc @zsuraski PHP 4.0
zsuraski authored
148 Keep one empty line between the variable decleration section and
149 the statements in a block, as well as between logical statement
150 groups in a block. Maintain at least one empty line between
151 two functions, preferably two.
152
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored
153 [4] When indenting, use the tab character. A tab is expected to represent
154 four spaces. It is important to maintain consistency in indenture so
155 that definitions, comments, and control structures line up correctly.
156
aceaabc @zsuraski PHP 4.0
zsuraski authored
157 Documentation and Folding Hooks
158 -------------------------------
159
160 In order to make sure that the online documentation stays in line with
161 the code, each user-level function should have its user-level function
162 prototype before it along with a brief one-line description of what the
163 function does. It would look like this:
164
165 /* {{{ proto int abs(int number)
166 Return the absolute value of the number */
585e338 php4ize a bit.
Sterling Hughes authored
167 PHP_FUNCTION(abs)
168 {
aceaabc @zsuraski PHP 4.0
zsuraski authored
169 ...
170 }
171 /* }}} */
172
173 The {{{ symbols are the default folding symbols for the folding mode in
174 Emacs. vim will soon have support for folding as well. Folding is very
175 useful when dealing with large files because you can scroll through the
176 file quickly and just unfold the function you wish to work on. The }}}
177 at the end of each function marks the end of the fold, and should be on
178 a separate line.
179
180 The "proto" keyword there is just a helper for the doc/genfuncsummary script
181 which generates a full function summary. Having this keyword in front of the
182 function prototypes allows us to put folds elsewhere in the code without
183 messing up the function summary.
184
185 Optional arguments are written like this:
186
187 /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
188 Returns a header object with the defined parameters. */
aceaabc @zsuraski PHP 4.0
zsuraski authored
189
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored
190 And yes, please keep the prototype on a single line, even if that line
191 is massive.
192
193 New and Experimental Functions
194 -----------------------------------
195 To reduce the problems normally associated with the first public
196 implementation of a new set of functions, it has been suggested
197 that the first implementation include a file labeled 'EXPERIMENTAL'
198 in the function directory, and that the functions follow the
199 standard prefixing conventions during their initial implementation.
200
201 The file labelled 'EXPERIMENTAL' should include the following
202 information:
203 Any authoring infomration (known bugs, future directions of the module).
204 Ongoing status notes which may not be appropriate for CVS comments.
aceaabc @zsuraski PHP 4.0
zsuraski authored
205
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
206 Aliases & Legacy Documentation
207 -----------------------------------
208 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
209 names, for example, somedb_select_result and somedb_selectresult. For
210 documentation puposes, these will only be documented by the most
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
211 current name, with the aliases listed in the documentation for
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored
212 the parent function. For ease of reference, user-functions with
213 completely different names, that alias to the same function (such as
214 highlight_file and show_source), will be separately documented. The
215 proto should still be included, describing which function is aliased.
216
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored
217 Backwards compatible functions and names should be maintained as long
218 as the code can be reasonably be kept as part of the codebase. See
219 /phpdoc/README for me information on documentation.
Something went wrong with that request. Please try again.