Annotation of embedaddon/php/CODING_STANDARDS, revision 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