Annotation of embedaddon/php/CODING_STANDARDS, revision 1.1.1.1
1.1 misho 1: ========================
2: PHP Coding Standards
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. Since we are now
9: well into the version 4 releases, many sections have been recoded to use
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
62: use "<svn username here>_0". For example, #if FOO_0, where FOO is your
63: svn user foo. This allows easier tracking of why code was commented out,
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:
85: Naming Conventions
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,
154: without underscore delimiters (CampelCaps starting with a capital letter).
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:
166: Syntax and indentation
167: ----------------------
168:
169: 1. Never use C++ style comments (i.e. // comment). Always use C-style
170: comments instead. PHP is written in C, and is aimed at compiling
171: under any ANSI-C compliant compiler. Even though many compilers
172: accept C++-style comments in C code, you have to ensure that your
173: code would compile with other compilers as well.
174: The only exception to this rule is code that is Win32-specific,
175: because the Win32 port is MS-Visual C++ specific, and this compiler
176: is known to accept C++-style comments in C code.
177:
178: 2. Use K&R-style. Of course, we can't and don't want to
179: force anybody to use a style he or she is not used to, but,
180: at the very least, when you write code that goes into the core
181: of PHP or one of its standard modules, please maintain the K&R
182: style. This applies to just about everything, starting with
183: indentation and comment styles and up to function declaration
184: syntax. Also see Indentstyle_.
185:
186: .. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
187:
188: 3. Be generous with whitespace and braces. Keep one empty line between the
189: variable declaration section and the statements in a block, as well as
190: between logical statement groups in a block. Maintain at least one empty
191: line between two functions, preferably two. Always prefer::
192:
193: if (foo) {
194: bar;
195: }
196:
197: to:
198:
199: if(foo)bar;
200:
201: 4. When indenting, use the tab character. A tab is expected to represent
202: four spaces. It is important to maintain consistency in indenture so
203: that definitions, comments, and control structures line up correctly.
204:
205: 5. Preprocessor statements (#if and such) MUST start at column one. To
206: indent preprocessor directives you should put the # at the beginning
207: of a line, followed by any number of whitespace.
208:
209: Testing
210: -------
211:
212: 1. Extensions should be well tested using *.phpt tests. Read about that
213: in README.TESTING.
214:
215: Documentation and Folding Hooks
216: -------------------------------
217:
218: In order to make sure that the online documentation stays in line with
219: the code, each user-level function should have its user-level function
220: prototype before it along with a brief one-line description of what the
221: function does. It would look like this::
222:
223: /* {{{ proto int abs(int number)
224: Returns the absolute value of the number */
225: PHP_FUNCTION(abs)
226: {
227: ...
228: }
229: /* }}} */
230:
231: The {{{ symbols are the default folding symbols for the folding mode in
232: Emacs and vim (set fdm=marker). Folding is very useful when dealing with
233: large files because you can scroll through the file quickly and just unfold
234: the function you wish to work on. The }}} at the end of each function marks
235: the end of the fold, and should be on a separate line.
236:
237: The "proto" keyword there is just a helper for the doc/genfuncsummary script
238: which generates a full function summary. Having this keyword in front of the
239: function prototypes allows us to put folds elsewhere in the code without
240: messing up the function summary.
241:
242: Optional arguments are written like this::
243:
244: /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
245: Returns a header object with the defined parameters */
246:
247: And yes, please keep the prototype on a single line, even if that line
248: is massive.
249:
250: New and Experimental Functions
251: -----------------------------------
252: To reduce the problems normally associated with the first public
253: implementation of a new set of functions, it has been suggested
254: that the first implementation include a file labeled 'EXPERIMENTAL'
255: in the function directory, and that the functions follow the
256: standard prefixing conventions during their initial implementation.
257:
258: The file labelled 'EXPERIMENTAL' should include the following
259: information::
260:
261: Any authoring information (known bugs, future directions of the module).
262: Ongoing status notes which may not be appropriate for SVN comments.
263:
264: Aliases & Legacy Documentation
265: -----------------------------------
266: You may also have some deprecated aliases with close to duplicate
267: names, for example, somedb_select_result and somedb_selectresult. For
268: documentation purposes, these will only be documented by the most
269: current name, with the aliases listed in the documentation for
270: the parent function. For ease of reference, user-functions with
271: completely different names, that alias to the same function (such as
272: highlight_file and show_source), will be separately documented. The
273: proto should still be included, describing which function is aliased.
274:
275: Backwards compatible functions and names should be maintained as long
276: as the code can be reasonably be kept as part of the codebase. See
277: /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