本代码规范翻译自 Drupal 官方网站的代码规范文档(http://drupal.org/coding-standards),方便国内的 Drupal 开发人员更好的学习和遵循代码规范。优秀的开发人员应该有遵循高标准以及编写高质量代码的意识。:)
控制结构包含 if, for, while, switch 等等,下面是一个简单的 if 语句结构示例:
控制语句的关键词与左边括号之间应该有一个空格,以此来与函数调用进行区分。
即使在大括号是可选的情况下,也应当总是使用大括号。这样可以加强代码的可读性以及减少因嵌套带来的逻辑错误。
switch 语句结构示例:
do-while 语句结构示例:
<?php
// Key is only valid if it matches the current user's ID, as otherwise other
// users could access any user's things.
$is_valid_user = (isset($key) && !empty($user->uid) && $key == $user->uid);
// IP must match the cache to prevent session spoofing.
$is_valid_query = (isset($user->cache) ? $user->cache == ip_address() : FALSE);
// Alternatively, if the request query parameter is in the future, then it
// is always valid, because the galaxy will implode and collapse anyway.
$is_valid_query = $is_valid_cache || (isset($value) && $value >= time());
if ($is_valid_user || $is_valid_query) {
...
}
?>
调用函数时,函数名与左括号之间没有空格,除最后一个参数外,每个参数后的 , 都应跟上一个空格,如:
<?php
$var = foo($bar, $baz, $quux);
?>
如之前所说,等号两边应该各有一个空格。当有一系列相关语句时,出于可读性的考虑,可以适当增加空格的数量,如:
<?php
$short = foo($bar);
$long_variable = foo($baz);
?>
包含默认值的参数应当放在最后,当函数拥有返回值时,尽量返回便于理解的值:
<?php
function funstuff_system($system, $field = 'description') {
$system["description"] = t("This module inserts funny text into posts randomly.");
return $system[$field];
}
?>
当调用不带参数的类构造器时,始终包含括号
<?php
$foo = new MyClassName();
?>
带参数的类构造器
<?php
$foo = new MyClassName($arg1, $arg2);
?>
如果使用变量做为类名,需先为变量赋值,然后才调用类构造器:
<?php
$bar = 'MyClassName';
$foo = new $bar();
$baz = new $bar($arg1, $arg2);
?>
数组的值之间应使用空格分隔,赋值操作符号(=>)左右也应包含空格:
<?php
$some_array = array('hello', 'word', 'foo' => 'bar');
?>
当声明数组的字符长度超过80个字符(通常在构造表单和菜单时),应该将各元素分行、缩进编写:
<?php
$form['title'] = array(
'#type' => 'textfield',
'#title' => t('Title'),
'#size' => 60,
'#maxlength' => 128,
'#description' => t('The title of your node.'),
);
?>
注意:最后一个数组元素末尾有一个逗号,这并不是手误,而是避免有新元素加入到最后之后因缺少逗号而出现解析错误。(从某种程度上来讲,在最后一个数组元素末尾加上逗号是一种推荐的做法,甚至在向drupal.org提交代码时,一些代码规范检测脚本会因为最后一个元素没有添加逗号而出现警告提示。)
Drupal 对于单引号和双引号的使用并没有很强硬的标准,只需在同一模块内保持用法的统一即可。
使用单引号的效率要高于双引号,因为解析器不需要到引号之间查找变量。以下是使用双引号的两种情况:
在点与要连接字符串之间需要加入空格以加强代码可读性:
<?php
$string = 'Foo' . $bar;
$string = $bar . 'foo';
$string = bar() . 'foo';
$string = 'foo' . 'bar';
?>
如果只是简单地连接变量,可以使用双引号
<?php
$string = "foo $bar";
?>
使用连接赋值符(.=)时,需要在符号两侧预留空格
<?php
$string .= 'Foo';
$string .= $bar;
$string .= baz();
?>
注释规范单独在 Doxygen及注释格式规范页面 讨论
引入代码(Including Code)
任何无条件引用文件的情况下,使用 require_once(), 任何有条件引用文件的情况,则使用 include_once(). 这两条语句都会保证文件只被引入一次。
当从当前目录或子目录引入代码时,始终以点路径开头
<?php
include_once ./includes/mymodule_formatting.inc
?>
在 Drupal 7 及更新版本中,使用 DRUPAL_ROOT 常量:
<?php
require_once DRUPAL_ROOT . '/' . variable_get('cache_inc', 'includes/cache.inc');
?>
始终使用 <?php ?>
来界定PHP代码而不使用要 ?>。这是为了遵循Drupal规范,同时也便于代码在其它系统和平台中被引用。
自 Drupal 4.7 开始,最后的 ?> 都故意被忽略不写,原因如下:
PHP 语言要求除了代码块以外,大多数行尾都要跟上分号。Drupal 代码规范同样有此要求,并且对于代码块也是如此。以下是一个单行代码块的示例:
示例 URL(Example URL)
使用 example.com 表示所有示例 URLs
函数与变量名称应该使用小写字母,且单词之间使用下划线分隔。函数应该使用模块组/模块名称作为前缀,以避免与不同模块间的冲突。
持久变量是指通过 variable_get()/variable_set() 函数取得和设置的变量,变量名称应该使用小写字母,且单词之间使用下划线进行分隔。持久变量也应该使用模块组/模块名称作为前缀,以避免与不同模块间的冲突。
<?php
/**
* Indicates that the item should be removed at the next general cache wipe.
*/
const CACHE_TEMPORARY = -1;
?>
<?php
if (!defined('MAINTENANCE_MODE')) {
define('MAINTENANCE_MODE', 'error');
}
?>
定义全局变量时,应当使用下划线加模块/主题名称开头
类名应使用驼峰式命名(即单词首字母大写)
<?php
abstract class DatabaseConnection extends PDO {
?>
类中的方法(函数)和属性(成员变量)应使用首字母小写的驼峰式
<?php
public $lastStatement;
?>
定义访问权限时,使用 protected 而代替 private,从而其它的类可以在必要时扩展和更新方法。Protected 和 public 函数和变量不应以下划线开头。
更多关于面向对象的编码规范
所有文档文件都应加上 .txt 后缀,以便于 Windows 用户查看。同时,所有文件名称应该全部大写,而文件后缀应该全部小写。
如 README.txt, INSTALL.txt, TODO.txt, CHANGELOG.txt 等等。