mirror of
https://github.com/php/php-src.git
synced 2024-09-22 10:27:25 +00:00
239 lines
7.4 KiB
Plaintext
239 lines
7.4 KiB
Plaintext
===========================================================================
|
|
|| PEAR Coding Standards ||
|
|
===========================================================================
|
|
|
|
$Id$
|
|
|
|
-------------
|
|
[1] Indenting
|
|
=============
|
|
|
|
Use an indent of 4 spaces, with no tabs. If you use Emacs to edit PEAR
|
|
code, you should set indent-tabs-mode to nil. Here is an example mode
|
|
hook that will set up Emacs according to these guidelines (you will
|
|
need to ensure that it is called when you are editing php files):
|
|
|
|
(defun php-mode-hook ()
|
|
(setq tab-width 4
|
|
c-basic-offset 4
|
|
c-hanging-comment-ender-p nil
|
|
indent-tabs-mode nil))
|
|
|
|
Here are vim rules for the same thing:
|
|
|
|
set expandtab
|
|
set shiftwidth=4
|
|
set tabstop=4
|
|
|
|
|
|
----------------------
|
|
[2] Control Structures
|
|
======================
|
|
|
|
These include if, for, while, switch, etc. Here is an example if statement,
|
|
since it is the most complicated of them:
|
|
|
|
if ((condition1) || (condition2)) {
|
|
action1;
|
|
} elseif ((condition3) && (condition4)) {
|
|
action2;
|
|
} else {
|
|
defaultaction;
|
|
}
|
|
|
|
Control statements should have one space between the control keyword
|
|
and opening parenthesis, to distinguish them from function calls.
|
|
|
|
You are strongly encouraged to always use curly braces even in
|
|
situations where they are technically optional. Having them increases
|
|
readability and decreases the likelihood of logic errors being
|
|
introduced when new lines are added.
|
|
|
|
For switch statements:
|
|
|
|
switch (condition) {
|
|
case 1:
|
|
action1;
|
|
break;
|
|
|
|
case 2:
|
|
action2;
|
|
break;
|
|
|
|
default:
|
|
defaultaction;
|
|
break;
|
|
|
|
}
|
|
|
|
|
|
------------------
|
|
[3] Function Calls
|
|
==================
|
|
|
|
Functions should be called with no spaces between the function name,
|
|
the opening parenthesis, and the first parameter; spaces between commas
|
|
and each parameter, and no space between the last parameter, the
|
|
closing parenthesis, and the semicolon. Here's an example:
|
|
|
|
$var = foo($bar, $baz, $quux);
|
|
|
|
As displayed above, there should be one space on either side of an
|
|
equals sign used to assign the return value of a function to a
|
|
variable. In the case of a block of related assignments, more space
|
|
may be inserted to promote readability:
|
|
|
|
$short = foo($bar);
|
|
$long_variable = foo($baz);
|
|
|
|
|
|
------------------------
|
|
[4] Function Definitions
|
|
========================
|
|
|
|
Function declaractions follow the "one true brace" convention:
|
|
|
|
function fooFunction($arg1, $arg2 = '')
|
|
{
|
|
if (condition) {
|
|
statement;
|
|
}
|
|
return $val;
|
|
}
|
|
|
|
Arguments with default values go at the end of the argument list.
|
|
Always attempt to return a meaningful value from a function if one is
|
|
appropriate. Here is a slightly longer example:
|
|
|
|
function connect(&$dsn, $persistent = false)
|
|
{
|
|
if (is_array($dsn)) {
|
|
$dsninfo = &$dsn;
|
|
} else {
|
|
$dsninfo = DB::parseDSN($dsn);
|
|
}
|
|
|
|
if (!$dsninfo || !$dsninfo['phptype']) {
|
|
return $this->raiseError();
|
|
}
|
|
|
|
return true;
|
|
}
|
|
|
|
|
|
------------
|
|
[5] Comments
|
|
============
|
|
|
|
Inline documentation for classes should follow the PHPDoc convention, similar
|
|
to Javadoc. More information about PHPDoc can be found here:
|
|
|
|
http://www.phpdoc.de/
|
|
|
|
Non-documentation comments are strongly encouraged. A general rule of
|
|
thumb is that if you look at a section of code and think "Wow, I don't
|
|
want to try and describe that", you need to comment it before you
|
|
forget how it works.
|
|
|
|
C++ style comments (/* */) and standard C comments (// ) are both
|
|
fine. Use of perl/shell style comments (# ) is discouraged.
|
|
|
|
|
|
------------------
|
|
[6] Including Code
|
|
==================
|
|
|
|
Anywhere you are unconditionally including a class file, use
|
|
require_once. Anywhere you are conditionally including a class file
|
|
(for example, factory methods), use include_once. Either of these will
|
|
ensure that class files are included only once. They share the same
|
|
file list, so you don't need to worry about mixing them - a file
|
|
included with require_once will not be included again by include_once.
|
|
|
|
Note: include_once and require_once are statements, not functions. You
|
|
don't need parentheses around the filename to be included.
|
|
|
|
|
|
-----------------
|
|
[7] PHP Code Tags
|
|
=================
|
|
|
|
ALWAYS use <?php ?> to delimit PHP code, not the <? ?> shorthand.
|
|
This is required for PEAR compliance and is also the most portable way
|
|
to include PHP code on differing operating systems and setups.
|
|
|
|
|
|
-------------------------
|
|
[8] Header Comment Blocks
|
|
=========================
|
|
|
|
All source code files in the core PEAR distribution should contain the
|
|
following comment block as the header:
|
|
|
|
/* vim: set expandtab tabstop=4 shiftwidth=4: */
|
|
// +----------------------------------------------------------------------+
|
|
// | PHP version 4.0 |
|
|
// +----------------------------------------------------------------------+
|
|
// | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group |
|
|
// +----------------------------------------------------------------------+
|
|
// | This source file is subject to version 2.0 of the PHP license, |
|
|
// | that is bundled with this package in the file LICENSE, and is |
|
|
// | available at through the world-wide-web at |
|
|
// | http://www.php.net/license/2_02.txt. |
|
|
// | If you did not receive a copy of the PHP license and are unable to |
|
|
// | obtain it through the world-wide-web, please send a note to |
|
|
// | license@php.net so we can mail you a copy immediately. |
|
|
// +----------------------------------------------------------------------+
|
|
// | Authors: Original Author <author@example.com> |
|
|
// | Your Name <you@example.com> |
|
|
// +----------------------------------------------------------------------+
|
|
//
|
|
// $Id$
|
|
|
|
There's no hard rule to determine when a new code contributer should be
|
|
added to the list of authors for a given source file. In general, their
|
|
changes should fall into the "substantial" category (meaning somewhere
|
|
around 10% to 20% of code changes). Exceptions could be made for rewriting
|
|
functions or contributing new logic.
|
|
|
|
Simple code reorganization or bug fixes would not justify the addition of a
|
|
new individual to the list of authors.
|
|
|
|
Files not in the core PEAR repository should have a similar block
|
|
stating the copyright, the license, and the authors. All files should
|
|
include the modeline comments to encourage consistency.
|
|
|
|
|
|
------------
|
|
[9] CVS Tags
|
|
============
|
|
|
|
Include the <dollar>Id CVS vendor tag in each file. As each
|
|
file is edited, add this tag if it's not yet present (or replace existing
|
|
forms such as "Last Modified:", etc.).
|
|
|
|
[NOTE: we have a custom $Horde tag in Horde cvs to track our versions
|
|
seperately; we could do the same and make a $PEAR tag, that would remain even
|
|
if PEAR files were put into another source control system, etc...]
|
|
|
|
|
|
-----------------
|
|
[10] Example URLs
|
|
=================
|
|
|
|
Use "example.com" for all example URLs, per RFC 2606.
|
|
|
|
|
|
---------------------
|
|
[11] Naming Constants
|
|
=====================
|
|
|
|
Constants should always be uppercase, with underscores to seperate
|
|
words. Prefix constant names with the name of the class/package they
|
|
are used in. For example, the constants used by the DB:: package all
|
|
begin with "DB_".
|
|
|
|
True and false are built in to the php language and behave like
|
|
constants, but should be written in lowercase to distinguish them from
|
|
user-defined constants.
|