Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

zh-cn:WordPress 代码规范

一些旧的 WordPress 的 PHP 代码结构在风格上不统一。WordPress 一直都努力逐步改善这个问题帮助用户维护一个统一的代码风格,使代码保持简洁、容易阅读。

不论是在编写 WordPress 核心代码、插件还是主题的时候,都请记住以下几点。这篇指南和 PEAR 编码规范在许多地方很相似,但在一些关键地方有所不同。

单引号和双引号
适当的使用单引号和双引号.如果你不在字符串中做计算,就使用单引号.你几乎不用在字符串中转义 html的引号,因为你可以像下面这样替换引用风格:
echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';
echo "<a href='$link' title='$linktitle'>$linkname</a>";
唯一的例外就是 JavaScript,因为有时候在一些地方必须使用单引号或者双引号。属性值的文本必须经过 attribute_escape() 函数的处理,以防单引号或者双引号终止属性值解析从而使 XHTML 失效,导致安全问题。
缩进
您的缩进应该能够反映出代码的逻辑结构.尽量使用tab而不要使用空格,因为这样能够保证有跨客户端编辑器软件的灵活性.
例外:你如果有段代码想要保持某些数据对齐更方便阅读,可以使用空格.如下:
总则:在行首使用tab,在行里面使用空格.
[tab]$foo   = 'somevalue';
[tab]$foo2  = 'somevalue2';
[tab]$foo34 = 'somevalue3';
[tab]$foo5  = 'somevalue4';
大括号的使用风格
大括号应该在含有多行的代码块中使用:
if ( condition ) {
    action1();
    action2();
} elseif ( condition2 && condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
}
此外,你如果有一个很长的代码块,考虑一下能不能把它拆成多个短点的代码块或者写成一个函数.如果你觉得不能避免这样长代码块,那么最好能够在代码块的结尾做一个简短的注释,告诉阅读代码的人这时一个大括号的结束---比较典型的就是35行以上的逻辑代码块.当然,不是能很直观的看出来结构的代码都应该注释一下.
为了简洁,只含有一行的代码块可以省去大括号:
if ( condition )
    action1();
elseif ( condition2 )
    action2();
else
    action3();
如果任何一个逻辑相关(比如判断)的代码块含有多行代码,那么所有的相关代码块都应该用大括号包含.
if ( condition ) {
    action1();
} elseif ( condition2 ) {
    action2a();
    action2b();
}
循环应该总是放到大括号里面以增强可读性,这样一来也可以允许调试或者增加额外的功能编辑里面的代码.
foreach ( $items as $item ) {
    process_item( $item );
}
include_once和require_once
要知道include_once和require_once的不同然后正确的使用它们.我们这里引用一下php的官方文档的解释:"这两种结构除了在处理错误信息之外是等同的.include()产生警告信息,require()产生致命错误",致命错误会使终止脚本的运行.
正则表达式
应该使用符合POSIX的perl兼容的正则表达式,使用preg_replace_callback,不要使用/e开关.
不要使用php短标签
不要使用简短的php标签(<? ... ?>或者<?=$vars?>),应该使用php完整标签<?php ... ?>,保证在关闭标签后不要有任何空格.
空格的使用
在逗号后面和逻辑操作符与赋值符的两边添加空格.比如:"x == 1","$foo && $bar","array( 1, 2, 3, 4 )".在if, elseif, foreach, for , switch的开始和结束括号两边也同样要添加空格.(例如:foreach ( $foo as $bar ) { ...)定义一个函数的时候这样做:function myfunction( $param1 = 'foo', $param2 = 'bar' ) {,调用函数的时候这样:myfunction( $param1, funcparam( $param2 ) );
格式化SQL语句
编写时可以把较为复杂SQL语句拆分成带缩进的几行,使得复杂的逻辑通俗易懂.当然,大部分的SQL语句写在一行也是可以工作的.要大写UPDATE,INSERT等SQL的关键字.
更新数据库的函数希望传递给他们的函数不要含有SQL的\转义,转义应该在数据库查询的时候执行,我们可以使用$wpdb->prepare().
$wpdb->prepare()是在SQL查询时候处理转义,引用,整型判定的函数.它使用sprintf()函数的子集.例如:
$var = "dangerous'"; // raw data that may or may not need to be escaped
$id  = some_foo_number(); // data we expect to be an integer, but we're not certain

$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );
%s是字符串的占位符,%d是整型的占位符.注意他们没有被引号引起来.$wpdb->prepare()会为我们处理转义和引用的问题.这样就很容易看得出来哪些东西被转义了哪些没有,因为这会发生在数据库查询的时候.
数据库查询
避免直接动数据库.如果有一个函数可以得到你想得到的数据,那么就使用这个函数.数据库抽象层可以使你的代码向前兼容,如果查询结果在缓存中,使用函数就可以不用查询数据库,可以提高很多倍的访问速度.如果你必须要动数据库,在wp-hackers邮件列表发个帖子联系里面的开发人员,或许他们会考虑在下个版本中加入个实现你的功能的函数.(呵呵~)
变量,函数,文件名,操作符
变量名和函数名使用小写(不要使用驼峰格式),使用下划线做连字符.
function some_name( $some_variable ) { [...] }
使用小写的,带有描述性的文件名,用横线做连字符.
my-plugin-name.php
不要创建只使用一次的变量.这包括数据库查询.与数据库交互时使用wpdb类的函数.
三元操作符挺好用的.养成表达式为真的时候做测试的习惯,而不是假的时候,否则就会混淆.
// GOOD example:
// (if statement is true) ? (do this) : (if false, do this);
$musictype = ( 'jazz' == $music ) ? 'cool' : 'blah';
还有很重要的一点就是上面的这个例子.做逻辑比较的时候把变量放到右边.试想:如果你忘记了其中一个等号,把变量放到右边就会抛出一个解析错误,而放在左边就会是一个赋值操作而执行了.这不需要花费额外的时间去做,但是如果因此解决了一个bug,那么就值了.
使用见名知意的函数参数名称
调用函数时使用描述性的字符串而不是单单的true和false.
//BAD
function eat( $what, $slowly = true ) {
    ...
}
eat( 'mushrooms' );
eat( 'mushrooms', true ); // what does true mean?
eat( 'dogfood', false ); // what does false mean? The opposite of true?
因为php不支持命名参数,如果参数名称没有任何意义,我们每遇到这样的函数都得去查函数定义.我们可以使用描述性的参数标记使函数更具可读性.替换上面的布尔类型:
//GOOD
function eat( $what, $speed = 'slowly' ) {
    ...
}
eat( 'mushrooms' );
eat( 'mushrooms', 'slowly' );
eat( 'dogfood', 'fast' );
本文已被标记为需要加工。欢迎您踊跃编辑,来帮助 Codex。