mirror of
https://github.com/php/php-src.git
synced 2026-04-26 09:28:21 +02:00
* point people to the manual instead
This commit is contained in:
Stig Bakken
+2
-248
@@ -4,251 +4,5 @@
|
||||
|
||||
$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
|
||||
(not
|
||||
(and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name))
|
||||
(string-match "\.php$" (buffer-file-name))))))
|
||||
|
||||
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;
|
||||
}
|
||||
|
||||
Functions should be named using the "studly caps" style (also referred to as
|
||||
"bumpy case" or "camel caps"). The initial letter of the name is lowercase,
|
||||
and each letter that starts a new "word" is capitalized. Some examples:
|
||||
|
||||
connect() getData() buildSomeWidget()
|
||||
|
||||
Private class members (meaning class members that an intented to be used
|
||||
only from within the same class in which they are declared; PHP does not yet
|
||||
support truly-enforceable private namespaces) are preceeded by a single
|
||||
underscore. For example:
|
||||
|
||||
_sort() _initTree() $_status
|
||||
|
||||
|
||||
------------
|
||||
[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.
|
||||
This document is no longer maintained, see
|
||||
http://php.net/manual/en/pear.standards.php instead.
|
||||
|
||||
Reference in New Issue
Block a user