在一个开发项目中,代码书写规范是非常重要的,特别是对于开发人员较多的项目。好的代码书写规范能确保高质量,减少BUG,并且容易维护。
接下来,我们谈谈Joomla! 开发过程中的代码书写规范 Coding Standards
缩进与行最大长度
1、采用tab缩进,每个tab四个空格宽度。
2、行最大长度在75-85字符之间,这并不是硬性的规定,你可以根据自己的需要设置。
控制结构
代码控制结构语句包括 if, for, while, switch等语句,下面是一个if语句声明:
3、结构控制语句关键词与条件之间采用一个空格分开,从而跟函数调用区分。
4、强烈推荐即使在不必书写大,小括号的情况下,也不要忘记,这样使代码容易阅读,不容易出现逻辑错误。
下面是switch语句的示例:
函数调用
函数调用在函数名称与小括号之间没有空格,而在左括号与第一个参数之间留一个空格位置,逗号与每个参数之间有一个空格,最后一个参数与右括号之间有一个空格,右括号与分号之间没有空格。以下是样例:
如上所示,在等号的两边应该各有一个空格,可以适当的在等号左边加tab,保证对齐美观。如下所示:
函数定义
类和函数定义遵循 "one true brace" 规范:
有默认值的参数在参数列表的尾部,要返回有意义的结果。以下是一个更长的例子:
注释
要归档的注释应该遵循PHPDoc规范,更详细的内容请查看http://www.phpdoc.org/
推荐一定写非归档注释,在你还明白代码是如何运行和执行什么功能之前,请做好注释。
C风格注释(/* */) 和C++风格(/ /)都可以,不鼓励使用perl风格注释(#)
Including Code
有条件引入的情况下使用require_once(),无条件引入使用include_once(),从而确保只引入一次类文件。
注意:include_once() 与 require_once()都是声明,而不是函数,可以不必用括号包含文件名。
PHP Code Tags
采用<?php ?>包含php代码,而不是<? ?>
对于只有php代码的文件,结束的 (?>)标记是不必的,这样做可以避免意外的给页面输出加多空格。
SQL 查询
15、SQL关键词应该大些,其他的应该小写,不使用回车,可是为了可读性可以合理使用缩进。(这点在Joomla!的代码中遵循的非常好,我看过的源代码中,Joomla! core的这部分是最为规范的,译者)
16、查询应该单引号包含,PHP解析单引号包含的文本更快(以前很少注意这个方面,Joomla!够深入)。
17、所有quoted字串应该用quoted 函数处理,从而兼容不同的数据库。
18、所有的整数,浮点应该做转换处理 (int), (float) or (double)
文件头部的注释块
19、所有的源代码文件应该包含下面的头部注释区域:
20、没有硬性规定新的开发人员是否应该在作者列表中增加,通常来说改动量在10%-20%以上一半会添加作者列表。当然如果是功能重写或者新的逻辑关系则要添加作者。
21、简单的代码重构或者BUG修复就不必添加作者列表了。
22、U使用 "example.com", "example.org" and "example.net" 作为所有URLs and email addresses的示例。
命名空间
类
类应该具有描述性的名称,尽可能的避免抽象。类名称首字母应该大写。
函数与方法
函数与方法命名应该是"studly caps"风格(忘了怎么翻译了,应该是大小写混排方式)。通常函数应该有包名前缀,从而避免命名冲突,前缀后的第一个字母小写,以后名称中每个单词首字母大写。以下是例子:
私有类成员(尽管PHP还不支持完全意义上的私有成员和函数)以下划线开头,以下是例子:
常量
常量应该总是大写的,单词之间用下划线连接,通常可以采用常量所在类或者包的名称大写做前缀,比如DB::包使用的前缀应该是DB_
全局变量
如果你的包要定义全局变量,全局变量应该以下划线开头,然后是包的名称大写,然后是变量名称,比如 $_PEAR_destructor_object_list.
Controllers
对于只有一个controller的组件,命名规范是[Name]Controller,而文件名称是controller.php.
对于有多个controller的组件,命名规范是[Component]Controller[Name].
文件放在组件的/controllers/目录中,文件名反应controller的名字。
Models
Models的命名规范是 [Component]Model[Name].
文件放在组件的/models/目录下。