Annotation of embedaddon/php/CODING_STANDARDS, revision 1.1.1.3
1.1 misho 1: ========================
2: PHP Coding Standards
3: ========================
4:
1.1.1.2 misho 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
1.1 misho 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. Since we are now
1.1.1.2 misho 9: well into version 5 releases, many sections have been recoded to use
1.1 misho 10: these rules.
11:
12: Code Implementation
13: -------------------
14:
15: 0. Document your code in source files and the manual. [tm]
16:
17: 1. Functions that are given pointers to resources should not free them
18:
19: For instance, ``function int mail(char *to, char *from)`` should NOT free
20: to and/or from.
21: Exceptions:
22:
23: - The function's designated behavior is freeing that resource. E.g. efree()
24:
25: - The function is given a boolean argument, that controls whether or not
26: the function may free its arguments (if true - the function must free its
27: arguments, if false - it must not)
28:
29: - Low-level parser routines, that are tightly integrated with the token
30: cache and the bison code for minimum memory copying overhead.
31:
32: 2. Functions that are tightly integrated with other functions within the
33: same module, and rely on each other non-trivial behavior, should be
34: documented as such and declared 'static'. They should be avoided if
35: possible.
36:
37: 3. Use definitions and macros whenever possible, so that constants have
38: meaningful names and can be easily manipulated. The only exceptions
39: to this rule are 0 and 1, when used as false and true (respectively).
40: Any other use of a numeric constant to specify different behavior
41: or actions should be done through a #define.
42:
43: 4. When writing functions that deal with strings, be sure to remember
44: that PHP holds the length property of each string, and that it
45: shouldn't be calculated with strlen(). Write your functions in a such
46: a way so that they'll take advantage of the length property, both
47: for efficiency and in order for them to be binary-safe.
48: Functions that change strings and obtain their new lengths while
49: doing so, should return that new length, so it doesn't have to be
50: recalculated with strlen() (e.g. php_addslashes())
51:
52: 5. NEVER USE strncat(). If you're absolutely sure you know what you're doing,
53: check its man page again, and only then, consider using it, and even then,
54: try avoiding it.
55:
56: 6. Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend
57: part of the source. Although the ``PHP_*`` macro's are mostly aliased to the
58: ``ZEND_*`` macros it gives a better understanding on what kind of macro
59: you're calling.
60:
61: 7. When commenting out code using a #if statement, do NOT use 0 only. Instead
1.1.1.3 ! misho 62: use "<git username here>_0". For example, #if FOO_0, where FOO is your
! 63: git user foo. This allows easier tracking of why code was commented out,
1.1 misho 64: especially in bundled libraries.
65:
66: 8. Do not define functions that are not available. For instance, if a
67: library is missing a function, do not define the PHP version of the
68: function, and do not raise a run-time error about the function not
69: existing. End users should use function_exists() to test for the
70: existence of a function
71:
72: 9. Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
73: counterparts. These functions implement an internal "safety-net"
74: mechanism that ensures the deallocation of any unfreed memory at the
75: end of a request. They also provide useful allocation and overflow
76: information while running in debug mode.
77:
78: In almost all cases, memory returned to the engine must be allocated
79: using emalloc().
80:
81: The use of malloc() should be limited to cases where a third-party
82: library may need to control or free the memory, or when the memory in
83: question needs to survive between multiple requests.
84:
1.1.1.3 ! misho 85: User Functions/Methods Naming Conventions
1.1 misho 86: ------------------
87:
88: 1. Function names for user-level functions should be enclosed with in
89: the PHP_FUNCTION() macro. They should be in lowercase, with words
90: underscore delimited, with care taken to minimize the letter count.
91: Abbreviations should not be used when they greatly decrease the
92: readability of the function name itself::
93:
94: Good:
95: 'mcrypt_enc_self_test'
96: 'mysql_list_fields'
97:
98: Ok:
99: 'mcrypt_module_get_algo_supported_key_sizes'
100: (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
101: 'get_html_translation_table'
102: (could be 'html_get_trans_table'?)
103:
104: Bad:
105: 'hw_GetObjectByQueryCollObj'
106: 'pg_setclientencoding'
107: 'jf_n_s_i'
108:
109: 2. If they are part of a "parent set" of functions, that parent should
110: be included in the user function name, and should be clearly related
111: to the parent program or function family. This should be in the form
112: of ``parent_*``::
113:
114: A family of 'foo' functions, for example:
115: Good:
116: 'foo_select_bar'
117: 'foo_insert_baz'
118: 'foo_delete_baz'
119:
120: Bad:
121: 'fooselect_bar'
122: 'fooinsertbaz'
123: 'delete_foo_baz'
124:
125: 3. Function names used by user functions should be prefixed
126: with ``_php_``, and followed by a word or an underscore-delimited list of
127: words, in lowercase letters, that describes the function. If applicable,
128: they should be declared 'static'.
129:
130: 4. Variable names must be meaningful. One letter variable names must be
131: avoided, except for places where the variable has no real meaning or
132: a trivial meaning (e.g. for (i=0; i<100; i++) ...).
133:
134: 5. Variable names should be in lowercase. Use underscores to separate
135: between words.
136:
137: 6. Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
138: or 'camel caps') naming convention, with care taken to minimize the
139: letter count. The initial letter of the name is lowercase, and each
140: letter that starts a new 'word' is capitalized::
141:
142: Good:
143: 'connect()'
144: 'getData()'
145: 'buildSomeWidget()'
146:
147: Bad:
148: 'get_Data()'
149: 'buildsomewidget'
150: 'getI()'
151:
152: 7. Classes should be given descriptive names. Avoid using abbreviations where
153: possible. Each word in the class name should start with a capital letter,
1.1.1.3 ! misho 154: without underscore delimiters (CamelCaps starting with a capital letter).
1.1 misho 155: The class name should be prefixed with the name of the 'parent set' (e.g.
156: the name of the extension)::
157:
158: Good:
159: 'Curl'
160: 'FooBar'
161:
162: Bad:
163: 'foobar'
164: 'foo_bar'
165:
1.1.1.3 ! misho 166: Internal Function Naming Convensions
! 167: ----------------------
! 168:
! 169: 1. Functions that are part of the external API should be named
! 170: 'php_modulename_function()' to avoid symbol collision. They should be in
! 171: lowercase, with words underscore delimited. Exposed API must be defined
! 172: in 'php_modulename.h'.
! 173:
! 174: PHPAPI char *php_session_create_id(PS_CREATE_SID_ARGS);
! 175:
! 176: Unexposed module function should be static and should not be defined in
! 177: 'php_modulename.h'.
! 178:
! 179: static int php_session_destroy(TSRMLS_D)
! 180:
! 181: 2. Main module source file must be named 'modulename.c'.
! 182:
! 183: 3. Header file that is used by other sources must be named 'php_modulename.h'.
! 184:
! 185:
1.1 misho 186: Syntax and indentation
187: ----------------------
188:
189: 1. Never use C++ style comments (i.e. // comment). Always use C-style
190: comments instead. PHP is written in C, and is aimed at compiling
191: under any ANSI-C compliant compiler. Even though many compilers
192: accept C++-style comments in C code, you have to ensure that your
193: code would compile with other compilers as well.
194: The only exception to this rule is code that is Win32-specific,
195: because the Win32 port is MS-Visual C++ specific, and this compiler
196: is known to accept C++-style comments in C code.
197:
198: 2. Use K&R-style. Of course, we can't and don't want to
199: force anybody to use a style he or she is not used to, but,
200: at the very least, when you write code that goes into the core
201: of PHP or one of its standard modules, please maintain the K&R
202: style. This applies to just about everything, starting with
203: indentation and comment styles and up to function declaration
1.1.1.3 ! misho 204: syntax. Also see Indentstyle.
1.1 misho 205:
1.1.1.3 ! misho 206: Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
1.1 misho 207:
208: 3. Be generous with whitespace and braces. Keep one empty line between the
209: variable declaration section and the statements in a block, as well as
210: between logical statement groups in a block. Maintain at least one empty
211: line between two functions, preferably two. Always prefer::
212:
213: if (foo) {
214: bar;
215: }
216:
217: to:
218:
219: if(foo)bar;
220:
221: 4. When indenting, use the tab character. A tab is expected to represent
222: four spaces. It is important to maintain consistency in indenture so
223: that definitions, comments, and control structures line up correctly.
224:
225: 5. Preprocessor statements (#if and such) MUST start at column one. To
226: indent preprocessor directives you should put the # at the beginning
227: of a line, followed by any number of whitespace.
228:
229: Testing
230: -------
231:
232: 1. Extensions should be well tested using *.phpt tests. Read about that
233: in README.TESTING.
234:
235: Documentation and Folding Hooks
236: -------------------------------
237:
238: In order to make sure that the online documentation stays in line with
239: the code, each user-level function should have its user-level function
240: prototype before it along with a brief one-line description of what the
241: function does. It would look like this::
242:
243: /* {{{ proto int abs(int number)
244: Returns the absolute value of the number */
245: PHP_FUNCTION(abs)
246: {
247: ...
248: }
249: /* }}} */
250:
251: The {{{ symbols are the default folding symbols for the folding mode in
252: Emacs and vim (set fdm=marker). Folding is very useful when dealing with
253: large files because you can scroll through the file quickly and just unfold
254: the function you wish to work on. The }}} at the end of each function marks
255: the end of the fold, and should be on a separate line.
256:
257: The "proto" keyword there is just a helper for the doc/genfuncsummary script
258: which generates a full function summary. Having this keyword in front of the
259: function prototypes allows us to put folds elsewhere in the code without
260: messing up the function summary.
261:
262: Optional arguments are written like this::
263:
264: /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
265: Returns a header object with the defined parameters */
266:
267: And yes, please keep the prototype on a single line, even if that line
268: is massive.
269:
270: New and Experimental Functions
271: -----------------------------------
272: To reduce the problems normally associated with the first public
273: implementation of a new set of functions, it has been suggested
274: that the first implementation include a file labeled 'EXPERIMENTAL'
275: in the function directory, and that the functions follow the
276: standard prefixing conventions during their initial implementation.
277:
278: The file labelled 'EXPERIMENTAL' should include the following
279: information::
280:
281: Any authoring information (known bugs, future directions of the module).
282: Ongoing status notes which may not be appropriate for SVN comments.
283:
284: Aliases & Legacy Documentation
285: -----------------------------------
286: You may also have some deprecated aliases with close to duplicate
287: names, for example, somedb_select_result and somedb_selectresult. For
288: documentation purposes, these will only be documented by the most
289: current name, with the aliases listed in the documentation for
290: the parent function. For ease of reference, user-functions with
291: completely different names, that alias to the same function (such as
292: highlight_file and show_source), will be separately documented. The
293: proto should still be included, describing which function is aliased.
294:
295: Backwards compatible functions and names should be maintained as long
296: as the code can be reasonably be kept as part of the codebase. See
297: /phpdoc/README for more information on documentation.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to CODING_STANDARDS CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php