[转]phpBB 编码标准规范

phpBB 编码标准规范

如果您对原手册内容有注解或建议，请发电子邮件至 [email protected] ；
如果您对本文翻译有什么意见或建议，请联系gaogan@BMY，或发电子邮件至[email protected]。

编辑器设定
命名约定
代码布局
一般规范


回到顶部

编辑器设定

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

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

回到顶部

命名约定

在我们的命名约定中，我们不会使用任何形式的匈牙利符号（译者注：原文如此，偶不明白）。我们很多人相信匈牙利命名是现行的导致代码混乱的主要技巧之一。

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

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

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

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

    例如：

函数名称：函数也应该描述性地命名。这里我们并非在用 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 文件开始

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

   例如：

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

   例如：

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

   例如：

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

   例如：

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

   例如：

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

   例如：

回到顶部

一般规范

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

   例如：

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

   例如：

注释：每个函数之前应当有注释告诉一个程序员使用这个函数所需要知道的每件事情。需要给出每个参数的意义，期望的输入，函数的输出作为一个最小化的注释。在错误条件下（还有具体是什么错误条件）这个函数的行为也应当给出。（注释应该确保）没有人为了能够在自己的代码中自信地调用这个函数不得不查看它的实际代码。

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

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

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

   例如：

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

   例如：

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

   例如：

回到顶部