Skip to content
Newer
Older
100644 219 lines (171 sloc) 8.73 KB
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
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 Nov 26, 2000
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 Apr 7, 1999
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 Sep 10, 2000
47 recalculated with strlen() (e.g. php_addslashes())
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
48
585e338 php4ize a bit.
Sterling Hughes authored Sep 10, 2000
49 [5] Use php_error() to report any errors/warnings during code execution.
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
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 Dec 19, 2000
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 Oct 18, 2000
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 Dec 19, 2000
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 Oct 18, 2000
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 Dec 19, 2000
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 Apr 7, 1999
99
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored Dec 19, 2000
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 Sep 10, 2000
106 with "_php_", and followed by a word or an underscore-delimited list of
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
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 Dec 19, 2000
110 [4] Variable names must be meaningful. One letter variable names must be
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
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 Oct 14, 2001
114 [5] Variable names should be in lowercase. Use underscores to separate
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
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 Nov 26, 2000
131 force anybody to use a style he or she is not used to, but,
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
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 Oct 14, 2001
135 indentation and comment styles and up to function declaration
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
136 syntax.
137
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored Nov 26, 2000
138 [3] Be generous with whitespace and braces. Always prefer:
139
140 if (foo) {
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
141 bar;
142 }
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored Nov 26, 2000
143
144 to:
145
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
146 if(foo)bar;
45807e6 @jparise Added a brief section documenting the preference of tabs over spaces.
jparise authored Nov 26, 2000
147
8a5402c Fixed some spelling errors.
Egon Schmid authored Oct 14, 2001
148 Keep one empty line between the variable declaration section and
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
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 Nov 26, 2000
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 Apr 7, 1999
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)
8a5402c Fixed some spelling errors.
Egon Schmid authored Oct 14, 2001
166 Returns the absolute value of the number */
585e338 php4ize a bit.
Sterling Hughes authored Sep 10, 2000
167 PHP_FUNCTION(abs)
168 {
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
169 ...
170 }
171 /* }}} */
172
173 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 Jun 5, 2001
174 Emacs and vim (set fdm=marker). Folding is very useful when dealing with
175 large files because you can scroll through the file quickly and just unfold
176 the function you wish to work on. The }}} at the end of each function marks
177 the end of the fold, and should be on a separate line.
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
178
179 The "proto" keyword there is just a helper for the doc/genfuncsummary script
180 which generates a full function summary. Having this keyword in front of the
181 function prototypes allows us to put folds elsewhere in the code without
182 messing up the function summary.
183
184 Optional arguments are written like this:
185
186 /* {{{ 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 Oct 14, 2001
187 Returns a header object with the defined parameters */
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
188
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored Dec 19, 2000
189 And yes, please keep the prototype on a single line, even if that line
190 is massive.
191
192 New and Experimental Functions
193 -----------------------------------
194 To reduce the problems normally associated with the first public
195 implementation of a new set of functions, it has been suggested
196 that the first implementation include a file labeled 'EXPERIMENTAL'
197 in the function directory, and that the functions follow the
198 standard prefixing conventions during their initial implementation.
199
200 The file labelled 'EXPERIMENTAL' should include the following
201 information:
8a5402c Fixed some spelling errors.
Egon Schmid authored Oct 14, 2001
202 Any authoring information (known bugs, future directions of the module).
5cc6344 Updated to reflect recent discussions on php-dev.
Ron Chmara authored Dec 19, 2000
203 Ongoing status notes which may not be appropriate for CVS comments.
aceaabc @zsuraski PHP 4.0
zsuraski authored Apr 7, 1999
204
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored Oct 18, 2000
205 Aliases & Legacy Documentation
206 -----------------------------------
207 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 Oct 18, 2000
208 names, for example, somedb_select_result and somedb_selectresult. For
8a5402c Fixed some spelling errors.
Egon Schmid authored Oct 14, 2001
209 documentation purposes, these will only be documented by the most
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored Oct 18, 2000
210 current name, with the aliases listed in the documentation for
aa20347 Updated naming standards as per 9/12 dev/doc discussion.
Ron Chmara authored Oct 18, 2000
211 the parent function. For ease of reference, user-functions with
212 completely different names, that alias to the same function (such as
213 highlight_file and show_source), will be separately documented. The
214 proto should still be included, describing which function is aliased.
215
d47e483 As per andi, similar names are for legacy reasons only.
Ron Chmara authored Oct 18, 2000
216 Backwards compatible functions and names should be maintained as long
217 as the code can be reasonably be kept as part of the codebase. See
8a5402c Fixed some spelling errors.
Egon Schmid authored Oct 14, 2001
218 /phpdoc/README for more information on documentation.
Something went wrong with that request. Please try again.