phpBB 编码标准规范

以前发过，今天又校对了一下，也当是自己又重新温习了一遍，又有新的感觉。
不愧是久负盛名的开源项目，编码规范简单精练，切中要害。
希望能对大家有所帮助，欢迎交流看法。 

phpBB 编码标准规范

如果您对原手册内容有注解或建议，请发电子邮件至 nate@phpbb.com ；
如果您对本文翻译有什么意见或建议，请联系QQ78045595，或发电子邮件至gaogan at gmail dot com.

编辑器设定

制表符 vs 空格：为了此事尽可能地简单，我们使用制表符，不用空格。 你可以随便设定编辑器使用多少空格显示制表符，但是必须保证当你保存文件时，它保存的是制表符而不是空格。 这样，我们每个人都可以让代码以我们喜欢的方式显示，同时不破坏实际文件的布局。

换行： 确保编辑器将文件保存为 Unix 格式。这意味着以换行符终止一行，而不是在 Win32 里那样用一个 CR/LF 对，也不是 Mac 所用的某种方式。任何规范的 Win32 编辑器应该做到这点，但这并不见得总是默认的。你需要熟悉你的编辑器。如果你需要有关使用 Windows 文本编辑器的建议，应该去咨询它的开发者。他们中有些人在 Win32 中做编辑工作。

命名约定

在我们的命名约定中，不会使用任何形式的匈牙利命名。我们很多人相信，匈牙利命名是导致代码混乱的一种主要手法。

变量名称：变量名应当全部小写，并且词语之间以单个下划线分隔。

例如： $current_user 是正确的， 但是 $currentuser 和 $currentUser 就不正确。

名称应当是描述性的，并且简明。我们自然不希望使用冗长的句子作为变量名，但是多输入几个字符总好于疑惑于某个变量到底是干什么用的。

循环计数器：允许使用一个单字符变量名的唯一情形是当它作为一个循环计数器的时候。在这种情况下，外层循环的计数器应当始终是 $i。如果有一个循环处于这个循环的内部，它的计数器应当是 $j，进而是 $k，等等。如果循环的计数器是一个已经存在并且名字有意义的变量，本规范并不适用。

例如：
 

1    for ($i = 0; $i < $outer_size; $i++)  
2    { 
3       for ($j = 0; $j < $inner_size; $j++)  
4       { 
5          foo($i, $j); 
6       } 
7    }
    view plain | print | copy to clipboard | ?

 


函数名称： 函数也应该描述性地命名。这里我们并非在用 C 编程，我们不希望写出诸如“stristr()”此类的函数来。同上，使用单词间用单下划线分隔的小写名称。函数名称中某处最好有一个动词。较好的函数名 称如print_login_status()， get_user_data()，等等。

函数参数：参数遵循和变量名字相同的约定。我们不希望一堆这样的函数：do_stuff($a, $b, $c)。在大部分情况下，我们希望仅仅看看函数的声明，就知道怎样使用它。

总结： 这里的基本哲学是不要为了偷懒而伤害了代码的清晰。但是，必须由一些常识来掌握这种平衡；例如， print_login_status_for_a_given_user() 做得就过火了——这个函数命名为 print_user_login_status() 更好些， 或只是 print_login_status()。

代码布局

新建文件的标准头部：这里是一个头部的模版，它应当包含在每个 phpBB 文件开始
 

1    /***************************************************************************
2                                    filename.php
3                                 -------------------
4        begin                : Sat June 17 2000
5        copyright            : &copy; 2000 The phpBB Group
6        email                : support@phpBB.com
7   
8        $Id: codingstandards.htm,v 1.3 2001/06/09 21:00:12 natec Exp $
9   
10     ***************************************************************************/
11     
12    /***************************************************************************
13     *                                                                             
14     *   这个程序是自由软件；你可以在自由软件基金会出版的
15     *   GNU 通用公共许可协议的条款下重新发布它和/或修改它；
16     *   或者该许可协议的第二版，或者（您自由选择）任何后来的版本。
17     *
18     ***************************************************************************/
    view plain | print | copy to clipboard | ?

 


始终包含大括号：这是因为懒于多敲两个字符而给代码清晰带来问题的又一个情形。 尽管有些结构的主体部分只有一行，千万不要丢掉大括号。绝对不要。

例如：

1    /* 这些都错了 */
2    if (condition)    do_stuff(); 
3    if (condition) 
4        do_stuff(); 
5    while (condition)  
6        do_stuff(); 
7    for ($i = 0; $i < size; $i++) 
8        do_stuff($i); 
9     
10    /* 这些是对的 */
11    if (condition)  
12    { 
13        do_stuff(); 
14    } 
15    while (condition)  
16    { 
17        do_stuff(); 
18    } 
19    for ($i = 0; $i < size; $i++)  
20    { 
21        do_stuff(); 
22    }
    view plain | print | copy to clipboard | ?

 


大括号放在哪儿：这一点是网络圣战（译者注：指网络上因基本观点不同产生的激烈争论） 的一部分，但是我们将使用一种可以用一句话总结的风格：大括号始终独占一行。终止大括号还应当与起始大括号处在同一列上。

例如：

1    if (condition)  
2    { 
3        while (condition2) 
4        { 
5      ... 
6        } 
7    } 
8    else  
9    { 
10        ... 
11    } 
12     
13    for ($i = 0; $i < $size; $i++)  
14    { 
15        ... 
16    } 
17     
18    while (condition)  
19    { 
20        ... 
21    } 
22     
23    function do_stuff()  
24    { 
25        ... 
26    }
    view plain | print | copy to clipboard | ?

 


符号之间使用空格：这是不用太费事就可以保持代码可读性的另一个简单，容易的步骤。 无论何时你写一个赋值，表达式，等等，始终在符号之间保留一个空格。基本上，把代码当作英语来写。在变量名和运算符之间插入空格。不要在起始括弧后或者终止括弧前加空格。不要在逗号或者分号之前加空格。一些例子很好地展示了这一点。

例如：
 

1    /* 每一对给出了错误方式，紧跟正确方式。 */
2     
3    $i=0; 
4    $i = 0; 
5     
6    if($i<7) ... 
7    if ($i < 7) ... 
8     
9    if ( ($i < 7)&&($j > 8) ) ... 
10    if (($i < 7) && ($j > 8)) ... 
11     
12    do_stuff( $i, "foo", $b ); 
13    do_stuff($i, "foo", $b); 
14     
15    for($i=0; $i<$size; $i++) ... 
16    for($i = 0; $i < $size; $i++) ... 
17     
18    $i=($j < $size)?0:1; 
19    $i = ($j < $size) ? 0 : 1;
    view plain | print | copy to clipboard | ?

 


运算符优先级：你知道 php 中所有运算符的详细的优先级吗？我也不知道。不要猜。始终用括号强制一个表达式的优先级可以使优先级明显，这样你知道它会做些什么。

例如：

1    /* 结果是什么？谁知道？ */
2    $bool = ($i < 7 && $j > 8 || $k == 4); 
3     
4    /* 现在你确定这里我在做什么了。 */
5    $bool = (($i < 7) && (($j < 8) || ($k == 4)))
    view plain | print | copy to clipboard | ?

 


sql 代码布局：既然我们都在使用不同的编辑器设置，不要尝试去做诸如在 sql 代码中实现列对齐此类的麻烦事。要做的是，不管用何种方法，把语句断行到它们单独的行上去。这里有一个 sql 代码看上去应该是什么样子的示例。注意在哪里断行，大写，和括号的用法。

例如：
 

1    SELECT field1 AS something, field2, field3 
2    FROM table a, table b 
3    WHERE (this = that) AND (this2 = that2)
    view plain | print | copy to clipboard | ?

 


sql insert 语句：SQL INSERT 语句可以写成两种不同方式。或者你明确指明要插入的列，或者你已经知道数据中各列的顺序，不用详细指定它们。我们希望使用前一种方法，也就是详细说明插入哪些列。这意味着应用程序代码不会依赖于数据库中字段的顺序，也不会因为我们增加另外的字段而崩溃（当然，除非它们被指定为 NOT NULL）。

例如：
 

1    # 这不是我们想要的 
2    INSERT INTO mytable 
3    VALUES ('something', 1, 'else') 
4     
5    # 这是正确的。 
6    INSERT INTO mytable (column1, column2, column3) 
7    VALUES ('something', 1, 'else')
    view plain | print | copy to clipboard | ?

 


一般规范

引用字符串：在 php 中有两种不同的方式引用字符串——使用单引号或使用双引号。主要区别是：解析器在双引号括起的字符串中执行变量替换，却不在单引号括起的字符串中执行。因此，应当始终使用单引号，除非你 确实需要对字符串进行变量替换。这样，我们可以避免让解析器解析一堆不需要执行替换的字符串的麻烦。同样，如果你使用字符串变量作为函数调用的一部分，你 不需要用引号把那个变量括起来。同样，那只会给解析器增加不必要的工作。无论如何，要注意几乎所有双引号中的转义序列在单引号中都不会起作用。如果这条规 范使你的代码难以阅读的话，要小心，并且放心地打破它。

例如：

1    /* 错误 */
2    $str = "This is a really long string with no variables for the parser to find."; 
3    do_stuff("$str"); 
4     
5    /* 正确 */
6    $str = 'This is a really long string with no variables for the parser to find.'; 
7    do_stuff($str);
    view plain | print | copy to clipboard | ?

 


关联数组的键名：在 php 中，使用一个不用引号括起来的字符串作为一个关联数组的键名是合法的。我们不想这样做——为了避免混乱，这个字符串应当用引号括起来。注意，这只是当我们使用字符串时的情况，不是当我们使用变量时的情况。

例如：
 

1    /* 错误 */
2    $foo = $assoc_array[blah]; 
3     
4    /* 正确 */
5    $foo = $assoc_array['blah'];
    view plain | print | copy to clipboard | ?

 


注释：每个函数之前应当有注释，告诉一个程序员使用这个函数所需要知道的事情。一个最小化的注释应包括：每个参数的意义，期望的输入，函数的输出。注释还应当给出在错误条件下（还有具体是什么错误条件）这个函数的行为。（注释应该确保）其他人不必察看这个函数的代码，就可以自信地在自己的代码中调用这个函数。

另外，为任何技巧性的，晦涩的或者并非显而易见的代码添加注释，无疑是我们应该做的事情。对文档尤其重要的是你的代码所做的任何假设，或者它正确运转的前提。任何一个开发者应该能够查看应用程序的任意部分，并且在合理的时间内断定（代码的执行中）发生了什么。

幻数（常数）： 不要使用它们。除非有明显的特殊情况，对任何一个精确值都应该使用命名常量。基本上，用字面的 0 检查一个数组是否有 0 个元素是 OK 的。而给一个数字以特殊意义并且到处直接使用它是不 OK 的。这会影响可读性和可维护性。按照本规范，我们应当使用常量 TRUE 和 FALSE 来代替字面上的 1 和 0——尽管它们有着相同的值，当你使用命名常量时逻辑会更加明显。

简化运算符： 简化自增($i++)和自减($i--)运算符是导致可读性问题的仅有的简化运算符。这些运算符不应当被用作表达式的一部分。然而，他们可以独占一行使用。在表达式中使用它们（带来的便利）还不够调试时头痛的（代价）。

例如：
 

1    /* 错误 */
2    $array[++$i] = $j; 
3    $array[$i++] = $k; 
4     
5     
6    /* 正确 */
7    $i++; 
8    $array[$i] = $j; 
9     
10    $array[$i] = $k; 
11    $i++;
    view plain | print | copy to clipboard | ?

 


条件表达式：条件表达式只应该用来做简单的事情。它们只适合拿来做赋值用，根本不是用来做函数调用或者任何复杂的事情的。如果使用不当，它们会影响可读性，所以不要沉迷于使用它们来减少打字。

例如：

1    /* 不应该使用它们的地方 */
2    (($i < $size) && ($j > $size)) ? do_stuff($foo) : do_stuff($bar); 
3     
4     
5    /* 使用它们的合适地方 */
6    $min = ($i < $j) ? $i : $j;
    view plain | print | copy to clipboard | ?

 


不要使用未初始化的变量：在 phpBB2 中，我们打算使用更高级别的运行时错误报告。这将意味着使用未初始化的变量不再会作为错误被报告。这个问题最容易在检查 HTML 表单传递了什么变量时出现。这些错误可以通过使用内嵌的 isset() 函数检查一个变量是否被设置来避免。

例如：
 

1    /* 老办法 */
2    if ($forum) ... 
3     
4     
5    /* 新办法 */
6    if (isset($forum)) ...