ECSHOP编码命名规范

ECSHOP v2 x 代码规范 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 ECSHOP v2 x 代码规范 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 康盛创想 北京 科技有限公司 并保留所有权利 网站地址 ECSHOP v2 x 代码规范 这是一个免费开源的软件 这意味着您可以在不用于商业目的的前提下对程序代 码 进行修改 使用和再发布 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 ECSHOP v2 x 代码规范 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 符号之间使用空格符号之间使用空格 这是不用太费事就可以保持代码可读性的另一个简单 容易的步骤 无论何时你写一个 赋值 表达式 等等 始终在符号之间保留一个空格 基本上 把代码当作英语来写 在 ECSHOP v2 x 代码规范 变量名和运算符之间插入空格 不要在起始括弧后或者终止括弧前加空格 不要在逗号或 者分号之前加空格 一些例子很好地展示了这一点 例如 每一对给出了错误方式 紧跟正确方式 i 0 i 0 if i 7 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 2 4 1 字符串连接符字符串连接符 当使用字符串连接符时必须在句点 两侧加上空格 错误的写法 str str 正确的写法 str 2 5 运算符优先级运算符优先级 你知道 PHP 中所有运算符的详细的优先级吗 我也不知道 不要猜 始终用括号强制 一个表达式的优先级可以使优先级明显 这样你知道它会做些什么 例如 结果是什么 谁知道 bool i 8 k 4 ECSHOP v2 x 代码规范 现在你确定这里我在做什么了 bool i 7 ECSHOP v2 x 代码规范 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 元素属性值的时候 我们要求所有语句均包含在双 引号之内 错误的代码 0 promote goods else nomarl goods if goods goods name 正确的写法 goods goods name 4 3 条件修饰符条件修饰符 在 smarty 中可以用 eq neq gt lt 等来分别表示 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 ECSHOP v2 x 代码规范 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 条件表达式条件表达式 条件表达式只应该用来做简单的事情 它们只适合拿来做赋值用 根本不是用来做函数 调用或者任何复杂的事情的 如果使用不当 它们会影响可读性 所以不要沉迷于使用它 们来减少打字 ECSHOP v2 x 代码规范 例如 不应该使用它们的地方 i 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 ECSHOP v2 x 代码规范 5 8 输入变量的初始化输入变量的初始化 无论是函数的参数还是通过 URL 传递的变量 在调用之前均必须对其进行预处理以及设 定默认值 字符串必须进行 trim 的处理 并且如果变量的值是在我们预计的范围之内 需要对变量的 非法值做出相应的处理 对于数字型的变量则需要进行 intval 或者 floatval 的处理 5 9 require 和和 include 在程序中需要使