php 编码规范

/**
 * PHP编码规范
 *
 * @since 2011-11-23 
 * @author PanZhibiao
 *
 * @lastmodify PanZhibiao, 2011-11-23
 */

函数命名, 变量命名, 文件命名应具备描述性; 不要过度缩写. 类型和变量应该是名词, 函数名可以用 “命令性” 动词.

如何命名: 尽可能给出描述性的名称. 不要节约行空间, 让别人很快理解你的代码更重要. 好的命名风格:

$num_errors;                  // Good.
$num_completed_connections;   // Good.

糟糕的命名使用含糊的缩写或随意的字符:

$n;                           // Bad - meaningless.
$nerr;                        // Bad - ambiguous abbreviation.
$n_comp_conns;                // Bad - ambiguous abbreviation.

缩写: 除非该缩写在其它地方都非常普遍, 否则不要使用. 例如:

// Good
// These show proper names with no abbreviations.
$num_dns_connections;  // 大部分人都知道 "DNS" 是啥意思.
$price_count_reader;   // OK, price count. 有意义.
 
// Bad!
// Abbreviations can be confusing or ambiguous outside a small group.
$wgc_connections;  // Only your group knows what this stands for.
$pc_reader;        // Lots of things can be abbreviated "pc".

$i, $j, $k固定用于循环或短小代码计数器。$_k, $_v固定用于foreach循环中：

foreach ($arr as $_k=>$_v) {
    foreach ($_v as $_k2=>$_v2) {
    }
}

文件名要全部小写, 可以包含下划线 (_) 或连字符 (-). 按项目约定来.

• 所有含有PHP代码的文件，都以.php结尾，防止用户意外看到代码逻辑。
• 通常应尽量让文件名更加明确. http_server_logs.php 就比 logs.php 要好. 定义类时文件名一般成对出现, 如foo_bar.php, 对应于类 FooBar.

类名称的每个单词首字母均大写, 不包含下划线: MyExcitingClass, MyExcitingEnum.

变量名一律小写, 单词之间用下划线连接. 类的成员变量以下划线结尾, 如:

$my_exciting_local_variable      // 普通变量
$my_exciting_member_variable_    // 类成员变量

• 普通变量命名:

举例:

$table_name;  // OK - uses underscore.
$tablename;   // OK - all lowercase.
 
$tableName;   // Bad - mixed case.

• 全局变量:

可以用$_或其它标志作为前缀、并大写, 以便更好的区分局部变量

$_TPL['xxx']; // 模板全局变量

• 常量命名：

使用define定义，字母全大写。单词之间采用下划线区分。

• 常规函数使用小写单词、单词之间采用下划线区分: my_exciting_member_variable(), set_my_exciting_member_variable()
• 可以采用前缀来表示用途的分类，如tpl_xxx表示模板函数系列
• 类方法采用首字母小写，后续单词采用驼峰命名。如：$obj→bindParam(), $obj→fetchEmailLists()
• 取值和设值函数则要求与变量名匹配：$obj→set_number(), $obj→get_number()，$number_是其成员变量

如果使用稳定的已有PHP库/代码包, 相关代码部分可参考其命名策略.

注释虽然写起来很痛苦, 但对保证代码可读性至关重要. 下面的规则描述了如何注释以及在哪儿注释. 当然也要记住: 注释固然很重要, 但最好的代码本身应该是自文档化. 有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字.

你写的注释是给代码读者看的: 下一个需要理解你的代码的人. 慷慨些吧, 下一个人可能就是你!

• 注释要言简意赅, 不要拖沓冗余, 复杂的东西简单化和简单的东西复杂化都是要被鄙视的
• 对于 Chinese coders 来说, 用英文注释还是用中文注释, it is a problem, 但不管怎样, 注释是为了让别人看懂, 难道是为了炫耀编程语言之外的你的母语或外语水平吗
• TODO 很不错, 有时候, 注释确实是为了标记一些未完成的或完成的不尽如人意的地方, 这样一搜索, 就知道还有哪些活要干, 日志都省了

总体采用Java注释风格，使用ZendStudio一般默认使用Java风格。

// 用于短小注释，空一格再写注释文字 
/* 用于描述区块注释，比如下面20行代码实现的功能，文字前后均空一格 */

对于重要核心的代码文件，如果你对原始作者的文件做了重大修改, 将你的信息添加到作者信息里. 这样当其他人对该文件有疑问时可以知道该联系谁。并填写修改原因。

/**
 * 获取用户Email列表
 * @params int $type_id
 * @params int $page_no
 * @params int $page_size
 * @return array
 */
function fetch_email_lists($type_id, $page_no, $page_size) {}
 
// 获取用户Email列表
function fetch_email_lists($type_id, $page_no, $page_size) {}

对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释.

// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
// TODO(Zeke) change this to use relations.

非常利于代码可读性

$jack          = 9;   // jack
$user_list_len = 89;  // user list length

代码风格和格式确实比较随意, 但一个项目中所有人遵循同一风格是非常容易的. 个体未必同意下述每一处格式规则, 但整个项目服从统一的编程风格是很重要的, 只有这样才能让所有人能很轻松的阅读和理解代码.

函数看上去像这样:

function_name(par_name1, par_name2) {
    do_something();
    ...
}
 
// 如果同一行文本太多, 放不下所有参数: 
really_long_function_name(par_name1,
                          par_name2,
                          par_name3) {
    do_something();
    ...
}

注意以下几点:

• 左圆括号总是和函数名在同一行;
• 函数名和左圆括号间没有空格;
• 圆括号与参数间没有空格;
• 左大括号总在最后一个参数同一行的末尾处;
• 右大括号总是单独位于函数最后一行;
• 右圆括号和左大括号间总是有一个空格;
• 所有形参应尽可能对齐;

尽量放在同一行, 否则, 将实参封装在圆括号中.

函数调用遵循如下形式:

$retval = do_something($argument1, $argument2, $argument3);
 
// 如果同一行放不下, 可断为多行, 后面每一行都和第一个实参对齐, 左圆括号后和右圆括号前不要留空格: 
$retval = do_something($averyveryveryverylongargument1,
                       $argument2, $argument3);
 
// 如果函数参数很多, 出于可读性的考虑可以在每行只放一个参数: 
$retval = do_something($argument1,
                       $argument2,
                       $argument3,
                       $argument4);

倾向于不在圆括号内使用空格. 关键字 else 另起一行.

对基本条件语句有两种可以接受的格式. 一种在圆括号和条件之间有空格, 另一种没有.

最常见的是没有空格的格式. 哪种都可以, 但 保持一致性. 如果你是在修改一个文件, 参考当前已有格式. 如果是写新的代码, 参考目录下或项目中其它文件. 还在徘徊的话, 就不要加空格了.

if (condition) {  // no spaces inside parentheses
    ...  // 4 space indent.
} else {  // The else goes on the same line as the closing brace.
    ...
}
 
// 如果你更喜欢在圆括号内部加空格: 
if ( condition ) {  // spaces inside parentheses - rare
    ...  // 4 space indent.
} else {  // The else goes on the same line as the closing brace.
    ...
}

注意所有情况下 if 和左圆括号间都有个空格. 右圆括号和左大括号之间也要有个空格:

if(condition)     // Bad - space missing after IF.
if (condition){   // Bad - space missing before {.
if(condition){    // Doubly bad.
 
if (condition) {  // Good - proper space after IF and before {.

如果能增强可读性, 简短的条件语句允许写在同一行. 只有当语句简单并且没有使用 else 子句时使用:

if (x == kFoo) return new Foo();
if (x == kBar) return new Bar();

如果语句有 else 分支则不允许:

// Not allowed - IF statement on one line when there is an ELSE clause
if (x) DoThis();
else DoThat();

通常, 单行语句不需要使用大括号, 但回车下来则必须加大括号，复杂的条件或循环语句必须加大括号

if (condition)
  do_something();  // Bad
 
if (condition) {
  do_something();  // Good
}
 
// Curly braces around both IF and ELSE required because
// one of the clauses used braces.
if (condition) {
  foo;
} else {
  bar;
}

空循环体应使用 {} 或 continue, 而不是一个简单的分号.

while (condition) {
  // Repeat test until it returns false.
}
for ($i = 0; $i < $number; ++$i) {}  // Good - empty body.
while (condition) continue;  // Good - continue indicates no logic.

逻辑与 (&&) 操作符总位于行尾. 可以考虑额外插入圆括号, 合理使用的话对增强可读性是很有帮助的.

if ($this_one_thing > $this_other_thing &&
    $a_third_thing == $a_fourth_thing &&
    $yet_another & $last_one) {
  ...
}