飞常哆科技编码规范.doc

代码规范 飞常哆（北京）科技有限公司飞常哆科技编码规范 v1.0飞常哆科技 R&D TEAM版本历史版本日期作者说明v1.02011-6-13章清平1. 编辑器设定1.1. 缩进所有的缩进使用空格取代Tab制表符。PHP文件采用4个空格的缩进，HTML文件以及HTML文件中嵌入的Javascript代码采用2个空格的缩进；单独的 Javascript以及CSS文件采用4个空格的缩进。1.2. 字符编码所有PHP、HTML文件均保存为No Bom UTF-8的字符编码。1.3. EditPlus 和 Dreamweaver 相关设定1.3.1. EditPlus相关设定1.3.2. Dreamweaver设定2. 命名约定2.1. 变量命名变量名应当全部小写，并且词语之间以单个下划线分隔。 例如： $current_user 是正确的， 但是 $currentuser 和 $CurrentUser 就不正确。名称应当是描述性的，并且简明。我们自然不希望使用冗长的句子作为变量名，但是多输入几个字符总好于疑惑于某个变量到底是干什么用的。2.2. 循环计数器允许使用一个单字符变量名的唯一情形是当它作为一个循环计数器的时候。在这种情况下，外层循环的计数器应当始终是 $i。如果有一个循环处于这个循环的内部，它的计数器应当是 $j，进而是 $k，等等。如果循环的计数器是一个已经存在并且名字有意义的变量，本规范并不适用。例如：for ($i = 0; $i $outer_size; $i+) for ($j = 0; $j $inner_size; $j+) foo($i, $j); 2.3. 函数名称函数也应该描述性地命名。这里我们并非在用 C 编程，我们不希望写出诸如“stristr()”此类的函数来。同上，使用单词间用单下划线分隔的小写名称。函数名称中某处最好有一个动词。较好的函数名称如print_login_status()， get_user_data()，等等。2.4. 函数参数参数遵循和变量名字相同的约定。我们不希望一堆这样的函数：do_stuff($a, $b, $c)。在大部分情况下，我们希望仅仅看看函数的声明，就知道怎样使用它。2.5. 类的名称类的名称首先必须是一个有意义的英文单词或者词组。同时在书写格式上为了使类名和函数、变量有一个区别，我们要求类的名称全小写的写法，并且加上cls_作为前缀。例如：/* 错误的写法 *class image_handle class imagehandle class imageHandle /* 正确的写法 *class cls_imagehandle 2.6. 总结这里的基本哲学是不要为了偷懒而伤害了代码的清晰。但是，必须由一些常识来掌握这种平衡；例如，print_login_status_for_a_given_user() 做得就过火了这个函数命名为 print_user_login_status() 更好些， 或只是 print_login_status()。 3. 代码布局这里是一个头部的模板，所有的PHP文件的开始都必须包含下面的内容：/* * 飞常哆科技 升级程序 之 控制器 * = * 版权所有 (C) 2005-2007 飞常哆科技（北京）科技有限公司，并保留所有权利。 * 网站地址: http:/www.飞常哆科技.com* =* $Author$ * $Date$ * $Id$*/3.1. 注释的写法根据流行的注释写法我们要求对于代码段的注释采用以下的方式来书写：/* 注释内容 */对于单行的注释则使用下面的注释形式，注意在/之后有一个空格：define(IN_ECS, ture); / 注释内容3.2. 始终包含大括号这是因为懒于多敲两个字符而给代码清晰带来问题的又一个情形。 尽管有些结构的主体部分只有一行，千万不要丢掉大括号。绝对不要。 例如： /* 这些都错了 */ if (condition) do_stuff(); if (condition) do_stuff(); while (condition) do_stuff(); for ($i = 0; $i size; $i+) do_stuff($i); /* 这些是对的 */ if (condition) do_stuff(); while (condition) do_stuff(); for ($i = 0; $i size; $i+) do_stuff(); 3.3. 大括号放在哪儿这一点是网络上争论比较多的一部分，但是我们将使用一种可以用一句话总结的风格：大括号始终独占一行。终止大括号还应当与起始大括号处在同一列上。 例如：if (condition) while (condition2) . else . for ($i = 0; $i $size; $i+) . while (condition) . function do_stuff() . 3.4. 符号之间使用空格这是不用太费事就可以保持代码可读性的另一个简单，容易的步骤。 无论何时你写一个赋值，表达式，等等，始终在符号之间保留一个空格。基本上，把代码当作英语来写。在变量名和运算符之间插入空格。不要在起始括弧后或者终止括弧前加空格。不要在逗号或者分号之前加空格。一些例子很好地展示了这一点。例如：/* 每一对给出了错误方式，紧跟正确方式。 */ $i=0; $i = 0; if($i7) . if ($i 7) . if ( ($i 8) ) . if ($i 8) . do_stuff( $i, foo, $b ); do_stuff($i, foo, $b); for($i=0; $i$size; $i+) . for($i = 0; $i $size; $i+) . $i=($j $size)?0:1; $i = ($j $size) ? 0 : 1;3.4.1. 字符串连接符当使用字符串连接符时必须在句点（.）两侧加上空格。/ 错误的写法$str = ;$str = ;/ 正确的写法$str = ;3.5. 运算符优先级你知道 PHP 中所有运算符的详细的优先级吗？我也不知道。不要猜。始终用括号强制一个表达式的优先级可以使优先级明显，这样你知道它会做些什么。例如：/* 结果是什么？谁知道？ */ $bool = ($i 8 | $k = 4); /* 现在你确定这里我在做什么了。 */ $bool = ($i 7) & ($j 8) | ($k = 4)3.6. 空行的使用谁也不愿意看到挤在一堆的无序的代码。我们在写代码的时候总是会利用一些空行来增加代码可读性。合理的利用空格来区分代码段会使代码的逻辑思路更加明确。我们强行规定的空行有以下两种情况：1、 之前必须有且只有1个空行3、两个函数之间必须有1个空行。4、return、die、exit之前如果有其他语句的情况下应加上一个空行。在代码中我们不允许仅有空格的空行，并且不允许在行尾有多余的空格。4. SQL 语句4.1. SQL 代码布局既然我们都在使用不同的编辑器设置，不要尝试去做诸如在 SQL 代码中实现列对齐此类的麻烦事。要做的是，不管用何种方法，把语句断行到它们单独的行上去。这里有一个 SQL 代码看上去应该是什么样子的示例。注意在哪里断行，大写，和括号的用法。 例如：SELECT field1 AS something, field2, field3 FROM table a, table b WHERE (this = that) AND (this2 = that2)4.2. 表名和字段值SQL语句中的表名必须使用符号包含起来；同时所有字段值的变量名必须包含在单引号之内，即便是整数值也必须有单引号。例如：/ 这是错误的INSERT INTO mytable (col1, col2, col3)VALUES ($val1, $val2, $val3)/ 这是正确的INSERT INTO mytable (col1, col2, col3)VALUES ($val1, $val2, $val3)4.3. SQL select 语句在已知需要查询的字段的前提下，不允许使用如下的代码：SELECT * FROM mytable取而代之的写法是将每一个字段名写上去，请不要偷懒。SELECT col1, col2, col3 FROM mytable在需要获得已知记录数量情况下，请使用 LIMIT offset, count 的方式，尽量不要使用无 LIMIT 的 SELECT 语句。在需要或者满足条件的记录数量的情况下，请使用 SELECT count(*|expr) FROM 的方式，尽量不要使用 SELECT expr FROM 的方式。需要进行逻辑运算的时候，尽量不要使用不等于，可以使用大于或者小于的方式。4.4. SQL insert 语句SQL INSERT 语句可以写成两种不同方式。或者你明确指明要插入的列，或者你已经知道数据中各列的顺序，不用详细指定它们。我们希望使用前一种方法，也就是详细说明插入哪些列。这意味着应用程序代码不会依赖于数据库中字段的顺序，也不会因为我们增加另外的字段而崩溃（当然，除非它们被指定为 NOT NULL）。例如： # 这不是我们想要的 INSERT INTO mytable VALUES (something, 1, else) # 这是正确的。 INSERT INTO mytable (column1, column2, column3) VALUES (something, 1, else)4.5. SQL语句中的单引号在SQL语句中字段值如果是变量必须是用单引号包围起来，无论这个变量是字符串还是数字。例如：$str = 飞常哆科技;$n = 1;$sql = “INSERT INTO table (string, number) VALUES ($str, $n)”;需要注意的是，如果字段的值是一个常量的数字，则不能使用单引号。5. Smarty语法5.1. 双引号、单引号为了避免dreamweaver将Smarty语句中的双引号改写为"，我们要求在Smarty的花括号中不允许使用双引号，而是使用单引号。错误的写法：if $user_name eq “”匿名用户/ifinsert name=”query_info”正确的写法：if $user_name eq 匿名用户/ifinsert name=query_info5.2. 有条件设置HTML属性值当需要在模板中有条件的设置HTML元素属性值的时候，我们要求所有语句均包含在双引号之内。错误的代码：0”promote_goods”else”nomarl_goods”/if$goods.goods_name正确的写法：$goods.goods_name5.3. 条件修饰符在smarty中可以用eq、neq、gt、lt等来分别表示=、!=、。6. 一般规范6.1. 引用字符串在 PHP 中有两种不同的方式引用字符串使用单引号或使用双引号。主要区别是：解析器在双引号括起的字符串中执行变量替换，却不在单引号括起的字符串中执行。因此，应当始终使用单引号，除非你确实需要对字符串进行变量替换。这样，我们可以避免让解析器解析一堆不需要执行替换的字符串的麻烦。同样，如果你使用字符串变量作为函数调用的一部分，你不需要用引号把那个变量括起来。同样，那只会给解析器增加不必要的工作。无论如何，要注意几乎所有双引号中的转义序列在单引号中都不会起作用。如果这条规范使你的代码难以阅读的话，要小心，并且放心地打破它。例如： /* 错误 */ $str = This is a really long string with no variables for the parser to find.; do_stuff($str); /* 正确 */ $str = This is a really long string with no variables for the parser to find.; do_stuff($str);6.2. 关联数组的键名在 PHP 中，使用一个不用引号括起来的字符串作为一个关联数组的键名是合法的。我们不想这样做为了避免混乱，这个字符串应当用引号括起来。注意，这只是当我们使用字符串时的情况，不是当我们使用变量时的情况。例如： /* 错误 */ $foo = $assoc_arrayblah; /* 正确 */ $foo = $assoc_arrayblah;6.3. 注释每个函数之前应当有注释，告诉一个程序员使用这个函数所需要知道的事情。一个最小化的注释应包括：每个参数的意义，期望的输入，函数的输出。注释还应当给出在错误条件下（还有具体是什么错误条件）这个函数的行为。（注释应该确保）其他人不必察看这个函数的代码，就可以自信地在自己的代码中调用这个函数。另外，为任何技巧性的，晦涩的或者并非显而易见的代码添加注释，无疑是我们应该做的事情。对文档尤其重要的是你的代码所做的任何假设，或者它正确运转的前提。任何一个开发者应该能够查看应用程序的任意部分，并且在合理的时间内断定（代码的执行中）发生了什么。6.4. 幻数（常数）不要使用它们。除非有明显的特殊情况，对任何一个精确值都应该使用命名常量。基本上，用字面的 0 检查一个数组是否有 0 个元素是 OK 的。而给一个数字以特殊意义并且到处直接使用它是不 OK 的。这会影响可读性和可维护性。按照本规范，我们应当使用常量 TRUE 和 FALSE 来代替字面上的 1 和 0尽管它们有着相同的值，当你使用命名常量时逻辑会更加明显。6.5. 简化运算符简化自增($i+)和自减($i-)运算符是导致可读性问题的仅有的简化运算符。这些运算符不应当被用作表达式的一部分。然而，他们可以独占一行使用。在表达式中使用它们（带来的便利）还不够调试时头痛的（代价）。例如： /* 错误 */ $array+$i = $j; $array$i+ = $k; /* 正确 */ $i+; $array$i = $j; $array$i = $k; $i+;6.6. 条件表达式条件表达式只应该用来做简单的事情。它们只适合拿来做赋值用，根本不是用来做函数调用或者任何复杂的事情的。如果使用不当，它们会影响可读性，所以不要沉迷于使用它们来减少打字。例如： /* 不应该使用它们的地方 */ ($i $size) ? do_stuff($foo) : do_stuff($bar); /* 使用它们的合适地方 */ $min = ($i $j) ? $i : $j;不要使用未初始化的变量：我们打算使用更高级别的运行时错误报告。这将意味着使用未初始化的变量不再会作为错误被报告。这个问题最容易在检查 HTML 表单传递了什么变量时出现。这些错误可以通过使用内嵌的 isset() 或者empty()函数检查一个变量是否被设置来避免。例如： /* 老办法 */ if ($forum) . /* 新办法 */ if (!empty($forum) .if （isset($forum)） 6.7. if 以及e