跳转到主要内容
东方龙马 提交于 24 January 2013

原文链接:http://drupal.org/coding-standards

Note: The Drupal Coding Standards apply to code within Drupal and its contributed modules. This document is loosely based on the PEAR Coding standards. Comments and names should use US English spelling (e.g., "color" not "colour").

注:Drupal 的编码规范适用于 Drupal 核心及其贡献模块的代码。此文件基于 PEAR 的编码规范编写。注释和名称应该使用美式英语的拼写(例如,“color” 而不是 “colour”)。

Drupal coding standards are version-independent and "always-current". All new code should follow the current standards, regardless of (core) version. Existing code in older versions may be updated, but doesn't necessarily have to be. Especially for larger code-bases (like Drupal core), updating the code of a previous version for the current standards may be too huge of a task. However, code in current versions should follow the current standards.

Drupal 的编码规范,是版本独立且与时俱进的。所有的新代码应该按照目前的规范,无论(核心)版本。在较旧版本的现有的代码可能会被更新,但并不一定是必须的。特别是对于较大型的基础代码(如 Drupal 核心),依照当前标准更新旧版本的代码或许是件巨大的工程。然而,当前版本的代码务必遵循当前的规范。

---------------------- 待译 ----------------------

Note: Do not squeeze coding standards updates/clean-ups into otherwise unrelated patches. Only touch code lines that are actually relevant. To update existing code for the current standards, always create separate and dedicated issues and patches.

See the Helper modules section at the bottom of this page for information on modules that can review code for coding standards problems (and in some cases, even fix the problems).

---------------------- //待译 ----------------------

 

缩进与空白字符(Indenting and Whitespace)

  • 使用 2 个空格而不使用 tab 键进行代码缩进(notepad++, Eclipse 等编辑器均支持此项配置);
  • 行尾不应该有空白字符
  • 应使用 \n (Unix换行符),而不是 \r\n (Windows 换行符)
  • 所有文件均应以一个空行结尾

运算符(Operators)

  • 所有二元运算符(二个值之间的运算符),如 +, -, =, !=, ==, > 等等,在运算符两端均需留有一个空格,如应该使用 $foo = $bar 而不是 $foo=$bar。
  • 所有一元运算符(只操作一个值班的运算符),例如 ++,在值与运算符之间则不应加入空格

转型(Casting)

  • 在 (type) 与要转型的变量之间应加入一个空格,如 (int) $mynumber.

控制结构(Control Structures)

控制结构包含 if, for, while, switch 等等,下面是一个简单的 if 语句结构示例:

控制语句的关键词与左边括号之间应该有一个空格,以此来与函数调用进行区分。

即使在大括号是可选的情况下,也应当总是使用大括号。这样可以加强代码的可读性以及减少因嵌套带来的逻辑错误。

switch 语句结构示例:

do-while 语句结构示例:

行长度与封装(Line length and wrapping)

  • 通常情况下,每行代码的长度不应超过80个字符
  • 以下情况,行长度可超过80个字符:当行内包含过长的函数名称、函数/类定义、变量声明等
  • 为方便阅读和理解,控制结构的行长度可超过80个字符
  • 控制条件(condition)不应该写作多行
  • 控制条件应该适当拆分以便于阅读和理解,编写代码时要避免以下情形:

将控制条件进行拆分,不仅便于阅读,同时也方便添加注释让人知道为何进行这样的条件判断:

函数调用(Function Calls)

调用函数时,函数名与左括号之间没有空格,除最后一个参数外,每个参数后的 , 都应跟上一个空格,如:

如之前所说,等号两边应该各有一个空格。当有一系列相关语句时,出于可读性的考虑,可以适当增加空格的数量,如:

类构造器调用(Class Constructor Calls)

当调用不带参数的类构造器时,始终包含括号

带参数的类构造器

如果使用变量做为类名,需先为变量赋值,然后才调用类构造器:

数组(Array)

数组的值之间应使用空格分隔,赋值操作符号(=>)左右也应包含空格:

当声明数组的字符长度超过80个字符(通常在构造表单和菜单时),应该将各元素分行、缩进编写:

注 意:最后一个数组元素末尾有一个逗号,这并不是手误,而是避免有新元素加入到最后之后因缺少逗号而出现解析错误。(从某种程度上来讲,在最后一个 数组元素末尾加上逗号是一种推荐的做法,甚至在向drupal.org提交代码时,一些代码规范检测脚本会因为最后一个元素没有添加逗号而出现警告提 示。)

引号(Quotes)

Drupal 对于单引号和双引号的使用并没有很强硬的标准,只需在同一模块内保持用法的统一即可。

使用单引号的效率要高于双引号,因为解析器不需要到引号之间查找变量。以下是使用双引号的两种情况:

  • 引号中间带有变量,如:
  • 引号中间带有单引号,使用双引号可避免对单引号的转义 当然也可以使用单引号,但 .pot 解析器不能很好的处理这种情况,而且看起来怪怪的

字符串连接(String Concatenations)

在点与要连接字符串之间需要加入空格以加强代码可读性:

使用连接赋值符(.=)时,需要在符号两侧预留空格

如果只是简单地连接变量,可以使用双引号

注释(Comment)

注释规范单独在 Doxygen及注释格式规范页面 讨论

引入代码(Including Code)

任何无条件引用文件的情况下,使用 require_once(), 任何有条件引用文件的情况,则使用 include_once(). 这两条语句都会保证文件只被引入一次。

当从当前目录或子目录引入代码时,始终以点路径开头

在 Drupal 7 及更新版本中,使用 DRUPAL_ROOT 常量:

PHP 代码标签(PHP Code Tags)

始终使用来界定PHP代码而不使用要 ?>。这是为了遵循Drupal规范,同时也便于代码在其它系统和平台中被引用。

自 Drupal 4.7 开始,最后的 ?> 都故意被忽略不写,原因如下:

  • 移除它可以避免在文件末尾出现空白字符,这些空白字符可能导致“文件头已发送(header already sent)”错误,XHTML/XML验证错误,及其它问题
  • PHP 官方说明结尾的PHP界定符是可选项
  • PHP.net 自身也移除了文件末尾的界定符(如 prepend.inc

分号(Semicolons)

PHP 语言要求除了代码块以外,大多数行尾都要跟上分号。Drupal 代码规范同样有此要求,并且对于代码块也是如此。以下是一个单行代码块的示例:

示例 URL(Example URL)

使用 example.com 表示所有示例 URLs

命名规范(Naming Conventions)

函数与变量(Functions and Variables)

函数与变量名称应该使用小写字母,且单词之间使用下划线分隔。函数应该使用模块组/模块名称作为前缀,以避免与不同模块间的冲突。

持久变量(Persistent Variables)

持久变量是指通过 variable_get()/variable_set() 函数取得和设置的变量,变量名称应该使用小写字母,且单词之间使用下划线进行分隔。持久变量也应该使用模块组/模块名称作为前缀,以避免与不同模块间的冲突。

常量(Constants)

  • 常量始终要求使用全大写字母,且单词之间使用下划线进行分隔。(包括PHP内置常量 TRUE, FALSE, NULL)
  • 模块中定义的常量需始终使用大写的模块名称作为前缀。
  • 在 Drupal 8 及之后,应使用 const 关键词代替 define() 函数来定义常量,因为效率更高 注意 const 不能用于PHP表达式,因此在条件判断和非字面值(non-literal value ???)时,还是应当使用 define() 函数

全局变量(Global Variables)

定义全局变量时,应当使用下划线加模块/主题名称开头

类(Class)

类名应使用驼峰式命名(即单词首字母大写)

类中的方法(函数)和属性(成员变量)应使用首字母小写的驼峰式

定义访问权限时,使用 protected 而代替 private,从而其它的类可以在必要时扩展和更新方法。Protected 和 public 函数和变量不应以下划线开头。

更多关于面向对象的编码规范

文件名(Filename)

所有文档文件都应加上 .txt 后缀,以便于 Windows 用户查看。同时,所有文件名称应该全部大写,而文件后缀应该全部小写。

如 README.txt, INSTALL.txt, TODO.txt, CHANGELOG.txt 等等。

辅助模块及工具

  • Coder 模块:可以遵循部分以上代码规范,对代码进行审查及修改建议
  • Drupal Code Sniffer:代码规范检测工具
  • PAReview.sh:还处理沙盒中的代码规范检测脚本,几乎严格遵守以上所有代码规范并给出修改建议。

 

(备注:本文大部分由lugir.com翻译。)

参考链接:http://lugir.com/drupal/coding-standards.html

Taxonomy upgrade extras