summaryrefslogtreecommitdiff
path: root/CODING_STANDARDS
diff options
context:
space:
mode:
Diffstat (limited to 'CODING_STANDARDS')
-rw-r--r--CODING_STANDARDS277
1 files changed, 277 insertions, 0 deletions
diff --git a/CODING_STANDARDS b/CODING_STANDARDS
new file mode 100644
index 0000000..7413be4
--- /dev/null
+++ b/CODING_STANDARDS
@@ -0,0 +1,277 @@
+========================
+ PHP Coding Standards
+========================
+
+This file lists several standards that any programmer adding or changing
+code in PHP should follow. Since this file was added at a very late
+stage of the development of PHP v3.0, the code base does not (yet) fully
+follow it, but it's going in that general direction. Since we are now
+well into version 5 releases, many sections have been recoded to use
+these rules.
+
+Code Implementation
+-------------------
+
+0. Document your code in source files and the manual. [tm]
+
+1. Functions that are given pointers to resources should not free them
+
+For instance, ``function int mail(char *to, char *from)`` should NOT free
+to and/or from.
+Exceptions:
+
+- The function's designated behavior is freeing that resource. E.g. efree()
+
+- The function is given a boolean argument, that controls whether or not
+ the function may free its arguments (if true - the function must free its
+ arguments, if false - it must not)
+
+- Low-level parser routines, that are tightly integrated with the token
+ cache and the bison code for minimum memory copying overhead.
+
+2. Functions that are tightly integrated with other functions within the
+ same module, and rely on each other non-trivial behavior, should be
+ documented as such and declared 'static'. They should be avoided if
+ possible.
+
+3. Use definitions and macros whenever possible, so that constants have
+ meaningful names and can be easily manipulated. The only exceptions
+ to this rule are 0 and 1, when used as false and true (respectively).
+ Any other use of a numeric constant to specify different behavior
+ or actions should be done through a #define.
+
+4. When writing functions that deal with strings, be sure to remember
+ that PHP holds the length property of each string, and that it
+ shouldn't be calculated with strlen(). Write your functions in a such
+ a way so that they'll take advantage of the length property, both
+ for efficiency and in order for them to be binary-safe.
+ Functions that change strings and obtain their new lengths while
+ doing so, should return that new length, so it doesn't have to be
+ recalculated with strlen() (e.g. php_addslashes())
+
+5. NEVER USE strncat(). If you're absolutely sure you know what you're doing,
+ check its man page again, and only then, consider using it, and even then,
+ try avoiding it.
+
+6. Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend
+ part of the source. Although the ``PHP_*`` macro's are mostly aliased to the
+ ``ZEND_*`` macros it gives a better understanding on what kind of macro
+ you're calling.
+
+7. When commenting out code using a #if statement, do NOT use 0 only. Instead
+ use "<svn username here>_0". For example, #if FOO_0, where FOO is your
+ svn user foo. This allows easier tracking of why code was commented out,
+ especially in bundled libraries.
+
+8. Do not define functions that are not available. For instance, if a
+ library is missing a function, do not define the PHP version of the
+ function, and do not raise a run-time error about the function not
+ existing. End users should use function_exists() to test for the
+ existence of a function
+
+9. Prefer emalloc(), efree(), estrdup(), etc. to their standard C library
+ counterparts. These functions implement an internal "safety-net"
+ mechanism that ensures the deallocation of any unfreed memory at the
+ end of a request. They also provide useful allocation and overflow
+ information while running in debug mode.
+
+ In almost all cases, memory returned to the engine must be allocated
+ using emalloc().
+
+ The use of malloc() should be limited to cases where a third-party
+ library may need to control or free the memory, or when the memory in
+ question needs to survive between multiple requests.
+
+Naming Conventions
+------------------
+
+1. Function names for user-level functions should be enclosed with in
+ the PHP_FUNCTION() macro. They should be in lowercase, with words
+ underscore delimited, with care taken to minimize the letter count.
+ Abbreviations should not be used when they greatly decrease the
+ readability of the function name itself::
+
+ Good:
+ 'mcrypt_enc_self_test'
+ 'mysql_list_fields'
+
+ Ok:
+ 'mcrypt_module_get_algo_supported_key_sizes'
+ (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
+ 'get_html_translation_table'
+ (could be 'html_get_trans_table'?)
+
+ Bad:
+ 'hw_GetObjectByQueryCollObj'
+ 'pg_setclientencoding'
+ 'jf_n_s_i'
+
+2. If they are part of a "parent set" of functions, that parent should
+ be included in the user function name, and should be clearly related
+ to the parent program or function family. This should be in the form
+ of ``parent_*``::
+
+ A family of 'foo' functions, for example:
+ Good:
+ 'foo_select_bar'
+ 'foo_insert_baz'
+ 'foo_delete_baz'
+
+ Bad:
+ 'fooselect_bar'
+ 'fooinsertbaz'
+ 'delete_foo_baz'
+
+3. Function names used by user functions should be prefixed
+ with ``_php_``, and followed by a word or an underscore-delimited list of
+ words, in lowercase letters, that describes the function. If applicable,
+ they should be declared 'static'.
+
+4. Variable names must be meaningful. One letter variable names must be
+ avoided, except for places where the variable has no real meaning or
+ a trivial meaning (e.g. for (i=0; i<100; i++) ...).
+
+5. Variable names should be in lowercase. Use underscores to separate
+ between words.
+
+6. Method names follow the 'studlyCaps' (also referred to as 'bumpy case'
+ or 'camel caps') naming convention, with care taken to minimize the
+ letter count. The initial letter of the name is lowercase, and each
+ letter that starts a new 'word' is capitalized::
+
+ Good:
+ 'connect()'
+ 'getData()'
+ 'buildSomeWidget()'
+
+ Bad:
+ 'get_Data()'
+ 'buildsomewidget'
+ 'getI()'
+
+7. Classes should be given descriptive names. Avoid using abbreviations where
+ possible. Each word in the class name should start with a capital letter,
+ without underscore delimiters (CampelCaps starting with a capital letter).
+ The class name should be prefixed with the name of the 'parent set' (e.g.
+ the name of the extension)::
+
+ Good:
+ 'Curl'
+ 'FooBar'
+
+ Bad:
+ 'foobar'
+ 'foo_bar'
+
+Syntax and indentation
+----------------------
+
+1. Never use C++ style comments (i.e. // comment). Always use C-style
+ comments instead. PHP is written in C, and is aimed at compiling
+ under any ANSI-C compliant compiler. Even though many compilers
+ accept C++-style comments in C code, you have to ensure that your
+ code would compile with other compilers as well.
+ The only exception to this rule is code that is Win32-specific,
+ because the Win32 port is MS-Visual C++ specific, and this compiler
+ is known to accept C++-style comments in C code.
+
+2. Use K&R-style. Of course, we can't and don't want to
+ force anybody to use a style he or she is not used to, but,
+ at the very least, when you write code that goes into the core
+ of PHP or one of its standard modules, please maintain the K&R
+ style. This applies to just about everything, starting with
+ indentation and comment styles and up to function declaration
+ syntax. Also see Indentstyle_.
+
+.. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html
+
+3. Be generous with whitespace and braces. Keep one empty line between the
+ variable declaration section and the statements in a block, as well as
+ between logical statement groups in a block. Maintain at least one empty
+ line between two functions, preferably two. Always prefer::
+
+ if (foo) {
+ bar;
+ }
+
+ to:
+
+ if(foo)bar;
+
+4. When indenting, use the tab character. A tab is expected to represent
+ four spaces. It is important to maintain consistency in indenture so
+ that definitions, comments, and control structures line up correctly.
+
+5. Preprocessor statements (#if and such) MUST start at column one. To
+ indent preprocessor directives you should put the # at the beginning
+ of a line, followed by any number of whitespace.
+
+Testing
+-------
+
+1. Extensions should be well tested using *.phpt tests. Read about that
+ in README.TESTING.
+
+Documentation and Folding Hooks
+-------------------------------
+
+In order to make sure that the online documentation stays in line with
+the code, each user-level function should have its user-level function
+prototype before it along with a brief one-line description of what the
+function does. It would look like this::
+
+ /* {{{ proto int abs(int number)
+ Returns the absolute value of the number */
+ PHP_FUNCTION(abs)
+ {
+ ...
+ }
+ /* }}} */
+
+The {{{ symbols are the default folding symbols for the folding mode in
+Emacs and vim (set fdm=marker). Folding is very useful when dealing with
+large files because you can scroll through the file quickly and just unfold
+the function you wish to work on. The }}} at the end of each function marks
+the end of the fold, and should be on a separate line.
+
+The "proto" keyword there is just a helper for the doc/genfuncsummary script
+which generates a full function summary. Having this keyword in front of the
+function prototypes allows us to put folds elsewhere in the code without
+messing up the function summary.
+
+Optional arguments are written like this::
+
+ /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
+ Returns a header object with the defined parameters */
+
+And yes, please keep the prototype on a single line, even if that line
+is massive.
+
+New and Experimental Functions
+-----------------------------------
+To reduce the problems normally associated with the first public
+implementation of a new set of functions, it has been suggested
+that the first implementation include a file labeled 'EXPERIMENTAL'
+in the function directory, and that the functions follow the
+standard prefixing conventions during their initial implementation.
+
+The file labelled 'EXPERIMENTAL' should include the following
+information::
+
+ Any authoring information (known bugs, future directions of the module).
+ Ongoing status notes which may not be appropriate for SVN comments.
+
+Aliases & Legacy Documentation
+-----------------------------------
+You may also have some deprecated aliases with close to duplicate
+names, for example, somedb_select_result and somedb_selectresult. For
+documentation purposes, these will only be documented by the most
+current name, with the aliases listed in the documentation for
+the parent function. For ease of reference, user-functions with
+completely different names, that alias to the same function (such as
+highlight_file and show_source), will be separately documented. The
+proto should still be included, describing which function is aliased.
+
+Backwards compatible functions and names should be maintained as long
+as the code can be reasonably be kept as part of the codebase. See
+/phpdoc/README for more information on documentation.