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>