ECSHOP编码命名规范

ECSHOP

编码规范

1.编辑器设定

1.1. 缩进

所有的缩进使用空格取代Tab制表符。PHP文件采用4个空格的缩进，HTML文件以及HTML文件中嵌入的Javascript代码采用2个空格的缩进；单独的Javascript以及CSS文件采用4个空格的缩进。

1.2. 字符编码

所有PHP、HTML文件均保存为No Bom UTF-8的字符编码。

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

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

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

1.3. 循环计数器

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

例如：

for ($i = 0; $i < $outer_size; $i++)

{

for ($j = 0; $j < $inner_size; $j++)

{

foo($i, $j);

}

}

1.4. 函数名称

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

1.5. 函数参数

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

1.6. 类的名称

类的名称首先必须是一个有意义的英文单词或者词组。同时在书写格式上为了使类名和函数、变量有一个区别，我们要求类的名称全小写的写法，并且加上cls_作为前缀。

例如：

/* 错误的写法 *

class image_handle {}

class imagehandle {}

class imageHandle {}

/* 正确的写法 *

class cls_imagehandle {}

1.7. 总结

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

2.代码布局

这里是一个头部的模板，所有的PHP文件的开始都必须包含下面的内容：

/**

* ECSHOP 升级程序之控制器

*

================================================================= ===========

* 版权所有 (C) 2005-2007 康盛创想（北京）科技有限公司，并保留所有权利。

* 网站地址: https://www.360docs.net/doc/375446476.html,

*

----------------------------------------------------------------------------

* 这是一个免费开源的软件；这意味着您可以在不用于商业目的的前提下对程序代码 * 进行修改、使用和再发布。

*

================================================================= ===========

* $Author$

* $Date$

* $Id$

*/

2.1. 注释的写法

根据流行的注释写法我们要求对于代码段的注释采用以下的方式来书写：

/* 注释内容 */

对于单行的注释则使用下面的注释形式，注意在//之后有一个空格：

define(…IN_ECS?, ture); // 注释内容

2.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();

}

2.3. 大括号放在哪儿

这一点是网络上争论比较多的一部分，但是我们将使用一种可以用一句话总结的风格：大括号始终独占一行。终止大括号还应当与起始大括号处在同一列上。

例如：

if (condition)

{

while (condition2)

{

...

}

}

else

{

...

}

for ($i = 0; $i < $size; $i++)

{

...

}

while (condition)

{

...

}

function do_stuff()

{

...

}

2.4. 符号之间使用空格

这是不用太费事就可以保持代码可读性的另一个简单，容易的步骤。无论何时你写一个赋值，表达式，等等，始终在符号之间保留一个空格。基本上，把代码当作英语来写。在变

量名和运算符之间插入空格。不要在起始括弧后或者终止括弧前加空格。不要在逗号或者分号之前加空格。一些例子很好地展示了这一点。

例如：

/* 每一对给出了错误方式，紧跟正确方式。 */

$i=0;

$i = 0;

if($i<7) ...

if ($i < 7) ...

if ( ($i < 7)&&($j > 8) ) ...

if (($i < 7) && ($j > 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;

2.4.1.字符串连接符

当使用字符串连接符时必须在句点（.）两侧加上空格。

// 错误的写法

$str = …?;

$str = …?;

// 正确的写法

$str = …?;

2.5. 运算符优先级

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

例如：

/* 结果是什么？谁知道？ */

$bool = ($i < 7 && $j > 8 || $k == 4);

/* 现在你确定这里我在做什么了。 */

$bool = (($i < 7) && (($j < 8) || ($k == 4)))

2.6. 空行的使用

谁也不愿意看到挤在一堆的无序的代码。我们在写代码的时候总是会利用一些空行来增加代码可读性。合理的利用空格来区分代码段会使代码的逻辑思路更加明确。我们强行规定的空行有以下两种情况：

1、

2、?> 之前必须有且只有1个空行

3、两个函数之间必须有1个空行。

4、return、die、exit之前如果有其他语句的情况下应加上一个空行。

在代码中我们不允许仅有空格的空行，并且不允许在行尾有多余的空格。

3.SQL 语句

3.1. SQL 代码布局

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

例如：

SELECT field1 AS something, field2, field3

FROM `table` a, `table` b

WHERE (this = that) AND (this2 = that2)

3.2. 表名和字段值

SQL语句中的表名必须使用`符号包含起来；同时所有字段值的变量名必须包含在单引号之内，即便是整数值也必须有单引号。

例如：

// 这是错误的

INSERT INTO mytable (col1, col2, col3)

VALUES ($val1, $val2, $val3)

// 这是正确的

INSERT INTO `mytable` (col1, col2, col3)

VALUES (…$val1?, …$val2?, …$val3?)

3.3. SQL select 语句

在已知需要查询的字段的前提下，不允许使用如下的代码：

SELECT * FROM `mytable`

取而代之的写法是将每一个字段名写上去，请不要偷懒。

SELECT col1, col2, col3 FROM `mytable`

在需要获得已知记录数量情况下，请使用LIMIT offset, count 的方式，尽量不要使用无LIMIT 的SELECT 语句。

在需要或者满足条件的记录数量的情况下，请使用SELECT count(*|expr) FROM 的方式，尽量不要使用SELECT expr FROM 的方式。

需要进行逻辑运算的时候，尽量不要使用不等于，可以使用大于或者小于的方式。

3.4. SQL insert 语句

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

例如：

# 这不是我们想要的

INSERT INTO `mytable`

VALUES ('something', 1, 'else')

# 这是正确的。

INSERT INTO `mytable` (column1, column2, column3)

VALUES ('something', 1, 'else')

3.5. SQL语句中的单引号

在SQL语句中字段值如果是变量必须是用单引号包围起来，无论这个变量是字符串还是数字。

例如：

$str = …ecshop?;

$n = 1;

$sql = “INSERT INTO table (string, number) VALUES (…$str?, …$n?)”; 需要注意的是，如果字段的值是一个常量的数字，则不能使用单引号。

4.Smarty语法

4.1. 双引号、单引号

为了避免dreamweaver将Smarty语句中的双引号改写为"，我们要求在Smarty的花括号中不允许使用双引号，而是使用单引号。

错误的写法：

{if $user_name eq “”}匿名用户{/if}

{insert name=”query_info”}

正确的写法：

{if $user_name eq …?}匿名用户{/if}

{insert name=?query_info?}

4.2. 有条件设置HTML属性值

当需要在模板中有条件的设置HTML元素属性值的时候，我们要求所有语句均包含在双引号之内。

错误的代码：

{if $promote_price>0}”promote_goods”

{else}”nomarl_goods”{/if}

>{$goods.goods_name}

正确的写法：

{$goods.goods_name}

4.3. 条件修饰符

在smarty中可以用eq、neq、gt、lt等来分别表示==、!=、>、<。那我们到底该使用哪种呢？

当Smarty语句出现在HTML标签内时不允许使用==、!=这类修饰符，如果使用了这类修饰符有可能导致该符号或者其他的HTML相关符号被Dreamweaver自动转义。

总之，尽量使用eq、gt等这类条件修饰符，避免直接使用==、>。

5.一般规范

5.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);

5.2. 关联数组的键名

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

例如：

/* 错误 */

$foo = $assoc_array[blah];

/* 正确 */

$foo = $assoc_array['blah'];

5.3. 注释

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

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

5.4. 幻数（常数）

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

5.5. 简化运算符

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

例如：

/* 错误 */

$array[++$i] = $j;

$array[$i++] = $k;

/* 正确 */

$i++;

$array[$i] = $j;

$array[$i] = $k;

$i++;

5.6. 条件表达式

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

例如：

/* 不应该使用它们的地方 */

(($i < $size) && ($j > $size)) ? do_stuff($foo) : do_stuff($bar);

/* 使用它们的合适地方 */

$min = ($i < $j) ? $i : $j;

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

例如：

/* 老办法 */

if ($forum) ...

/* 新办法 */

if (!empty($forum)) ...

if （isset($forum)）…

5.7. if 以及else if的写法

当条件语句中的条件存在多个，并且有变量值的判断的时候，需要把变量的判断语句放在其他的条件语句之前。

正确：

if ($val == 1 && function_exists(…ob_gzhandler?))

{}

错误

if (function_exists(…ob_gzhandler?) && $val == 1)

{}

虽然在PHP 中else if 和elseif 的作用基本上是一样的。但是为了代码的统一性（也有传言else if 会出现不稳定的情况），我们要求将elseif 之间不保留空格：

if ($bool == 2)

{

}

elseif ($n = 1)

{

}

5.8. 输入变量的初始化

无论是函数的参数还是通过URL传递的变量，在调用之前均必须对其进行预处理以及设定默认值。

字符串必须进行trim的处理,并且如果变量的值是在我们预计的范围之内，需要对变量的非法值做出相应的处理；对于数字型的变量则需要进行intval或者floatval的处理。

5.9. require和include

在程序中需要使用包含文件的时候我们要求使用require_once或者include_once，不允许使用require或者include。

对于程序必须包含的文件只能采用require_once，而对于某些有条件包含的文件在引用时只能使用include_once。

5.10. 语言项

为了避免在其他语言环境下出现问题，在程序中应尽量少使用或者不使用语言项与语言项或者变量拼接的处理方式。如：

$_LANG[…add?] . $_LANG[…goods?]

$_LANG[…add?] . $goods[…goods_name?]

正确的方法应该是采用sprintf函数来处理。