PEAR官方php编码标准 I

PEAR是什么：PHP Extension and Application Repository。这里面包含了很多的内容。我们暂时只对她的编码标准感兴趣。

PEAR列出了大约20条编码规则，这些规则的目的无非是让代码变干净，开发或维护变的清晰、容易，帮助程序猿们对自己的代码增加自信。

Indenting and Line Length，行的缩进和单行字符数

Use an indent of 4 spaces, with no tabs. This helps to avoid problems with diffs, patches, SVN history and annotations.

It is recommended to keep lines at approximately 75-85 characters long for better code readability. Paul M. Jones has some thoughts about that limit.

control structures，控制结构

These include if, for, while, switch, etc.

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.

Split long if statements onto several lines,把一些多条件的表达式写成多行

ternary operator,三元运算符如果比较长可以考虑将子表达式分成多行，问号和冒号各作为新行的开始：
$b = $condition3 && $condition4
? $foo_man_this_is_too_long_what_should_i_do
: $bar;

 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);

The CS（Code Standard） require lines to have a maximum length of 80 chars. Calling functions or methods with many parameters while adhering to CS is impossible in that cases. It is allowed to split parameters in function calls onto several lines:

$this->someObject->subObject->callThisFunctionWithALongName(
$parameterOne, $parameterTwo,
$aVeryLongParameterThree
);

Alignment of assignments:

To support readability, the equal signs may be aligned in block-related assignments:

$short  = foo($bar);
$longer = foo($baz);

这条觉得不怎么实用。

Class Definitions

Class declarations have their opening brace on a new line:

class Foo_Bar
{
//... code goes here
}

Function Definitions

Function declarations follow the “K&R style”。易用、实用，下面有定义。

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. 这个返回一个合适的值跟有必要，因为我们的系统除了入口有Exception，其他地方都没有，因此只有返回值来表示function的执行结果，比如曾经一度依稀记得485有些create方法，居然没有返回last insert id，这样很多时候listener就无法工作了。

Array

Assignments in arrays may be aligned. When splitting array definitions onto several lines, the last value may also have a trailing comma.

$some_array = array(
'fooooo' => 'bar',
'spam'   => 'ham',
);

Comments

Complete inline documentation comment blocks (docblocks) must be provided. Please read the Sample File and Header Comment Blocks sections of the Coding Standards to learn the specifics of writing docblocks for PEAR packages. Further information can be found on the phpDocumentor website. Non-documentation comments are strongly encouraged. 充分的phpDocumentor暂时可以不考虑，文件注释（inline documentation comment，docblocks）还是有必要写的.

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged. 我们代码里面也有#注释的。

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.”

Header Comment Blocks

All source code files in the PEAR repository shall contain a “page-level” docblock at the top of each file and a “class-level” docblock immediately above each class:

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
* Short description for file
*
* Long description for file (if any)...
*
* PHP version 5
*
* LICENSE: This source file is subject to version 3.01 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_01.txt.  If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license@php.net so we can mail you a copy immediately.
*
* @category   CategoryName
* @package    PackageName
* @author     Original Author <author@example.com>
* @author     Another Author <another@example.com>
* @copyright  1997-2005 The PHP Group
* @license    http://www.php.net/license/3_01.txt  PHP License 3.01
* @version    SVN: $Id$
* @link       http://pear.php.net/package/PackageName
* @see        NetOther, Net_Sample::Net_Sample()
* @since      File available since Release 1.2.0
* @deprecated File deprecated in Release 2.0.0
*/

/*
* Place includes, constant defines and $_GLOBAL settings here.
* Make sure they have appropriate docblocks to avoid phpDocumentor
* construing they are documented by the page-level docblock.
*/

/**
* Short description for class
*
* Long description for class (if any)...
*
* @category   CategoryName
* @package    PackageName
* @author     Original Author <author@example.com>
* @author     Another Author <another@example.com>
* @copyright  1997-2005 The PHP Group
* @license    http://www.php.net/license/3_01.txt  PHP License 3.01
* @version    Release: @package_version@
* @link       http://pear.php.net/package/PackageName
* @see        NetOther, Net_Sample::Net_Sample()
* @since      Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class Foo_Bar
{
}

这个代价有点大。可以舍得。

Naming Conventions

命名约定包括：类的命名、类内函数、全局变量、全局函数命名、常量命名。

类的命名我们系统统一是小写下划线命名；

类内函数命名pear说用驼峰式命名，但是感觉还是下划线命名好；只要环境允许应该严格用private protected public控制可访问性，在php4里用单下划线($_privatevar,_privatefunc)命名成员。这一点很重要，有的api里面的方法都搞不清楚是给外部调用的？还是自己内部调用的？还是多余的？

全局变量本来就不多，都走$GLOBALS，自己一般不会定义全局变量；

全局函数也用下划线式命名；

常量命名大写。

File Formats

这个说的是与pear社区互动有关的文件编码、声明、格式。

All scripts contributed to PEAR must:

• Be stored as ASCII text

Use ISO-8859-1 or UTF-8 character encoding. The encoding may be declared using declare(encoding = ‘utf-8′); at the top of the file.

• Be Unix formatted

“Unix formatted” means two things:

1) Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do. *nix、mac、win 的行结束符都不相同。

2) There should be one line feed after the closing PHP tag (?>). This means that when the cursor is at the very end of the file, it should be one line below the closing PHP tag. 每个文件结尾处（有 ?>或者无）都应该带一个空行。

参考资料：http://pear.php.net/

PEAR PHP编码标准：http://pear.php.net/manual/en/standards.php