Return to CODING_STANDARDS CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

php 5.4.29

    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 version 5 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 "<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,
   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: User Functions/Methods 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 (CamelCaps 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: 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: 
  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
  204:     syntax. Also see Indentstyle.
  205: 
  206:     Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
  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.