DoitPHP编码规范
一、引言
本规范基于PHP PEAR编码规范及PHPDocumentor注释规范等编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好一致的编程风格。以达到在团队协作中，事半功倍的开发效率。为了与时俱进，根据客观需求，本文档会不定期更新。
作者：tommy < streen003@gmail.com > 版权：DoitPHP Group < www.doitphp.com > 更新日期：2010年9月23日
二、适用范围
如无特殊说明，以下规则要求完全适用于DoitPHP项目(注：Doitphp的PHP框架文件，而非使用DoitPHP所开发的PHP项目)。如果你喜欢以下编码规范，也可以用在其它PHP开发项目。
三、 标准化的重要性和好处 “不以规矩，不成方圆”，当一个软件项目尝试着遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要，自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下，也可以减少编码出错的机会。缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。
1. 程序员可以了解任何代码，弄清程序的状况 2. 新人可以很快的适应环境
3. 防止新接触PHP的人出于节省时间的需要，自创一套风格并养成终生的习惯 4. 防止新接触PHP的人一次次的犯同样的错误 5. 在一致的环境下，人们可以减少犯错的机会 6. 程序员们有了一致的敌人
四、 PHP编码规范与原则 1、文件格式
1.1、文件编码：文件编码统一为UTF-8(注:非UTF-8+BOM)。 1.2、定界符：PHP 代码必须以完整的形式来定界即：“”。而短定界符“”将禁止使用。对于只含有php的代码文件,建议将文件结尾处的“?>”忽略掉，防止多余空格或其它字符影响代码。
1.3、代码缩进：缩进将使用制表符，不推荐使用空格（通常的缩进由四个空格组成）。主要目的是：为了尽可能地简单，高效地编写代码。虽然在不同的编辑器里， TAB 制表符的长度是不一样的,我们不会为了不必要的“编码优美”而牺牲程序的开发效率。本缩进规范也适用于JavaScript中的函数、类、逻辑结构、循环等。
1.4、代码长度：每行代码长度应控制在80个字符以内，最长不超过120个字符（具体
1
视实际情况而定，量力而行，情况特殊可以不遵守本规定）。
1.5、代码内容：每行结尾不允许有多余的空格或TAB制表符（确保你的编辑器保存文件为 Unix 格式，这意味着行是以换行符终止的）。禁止一个php文件出现两个或多个类，不过允许其它php代码存在。除了语言包注释配置文件,其它地方不能有中文。
1.6、代码注释：文件要有清晰的代码注释，注释风格采用phpDocumentor标准（相关网址:http://www.phpdoc.org/)
2、命名约定
命名是程序规划的核心。古人相信只要知道一个人真正的名字就会获得凌驾于那个人之上的不可思议的力量。只要你给事物想到正确的名字，就会给你以及后来的人带来比代码更强的力量。
名字就是事物在它所处的生态环境中一个长久而深远的结果。总的来说，只有了解系统的程序员才能为系统取出最合适的名字。如果所有的命名都与其自然相适合，则关系清晰，含义可以推导得出，一般人的推想也能在意料之中。
就一般约定而言，类、函数和变量的名字应该总是能够描述让代码阅读者能够容易的知道这些代码的作用。形式越简单、越有规则，就越容易让人感知和理解。应该避免使用模棱两可，晦涩不标准的命名。
2.1、文件名：文件名由字母数字和下划线组成，为方便和兼容不同操作系统，推荐字母统一小写。短横线 (\和空格是绝对不允许的。
注：controller文件, model文件,widget文件除外，此三种文件将采用驼峰命名法则。 (1)controller文件名:Controller文件名字和内容中类的名字相同(大小字母也一致的相同）,如建立index的controller文件，其名字为IndexController.class.php。解释：index首字母要大写，后再加上Controller,注意这个Controller也是首字母大写的。
(2)model文件名:model文件命名采用驼峰命名法则。model文件内容类的名字和文件名要一致,如建一个新Model文件，假设为demo的model文件。文件名字为：DemoModel.class.php。解释：原理同上。
(3)widget文件命名采用驼峰命名法则,Widget文件内容类的名字和文件名要一致。如建一个新widget文件，假设为demo的widget文件。文件名字为：DemoWidget.class.php。解释：原理同上。
2.2、文件扩展名：php文件扩展名为\（这个地球人都知道），不过下面几种情况例外：
类文件扩展名为“.class.php”且文件命名和类名一致(字母大小写也要一致); 配置文件扩展名为“.ini.php”; 函数文件扩展名为“.fun.inc.php”;
不能通过浏览器直接访问的php文件（用于被incldue调用的）扩展名建议为“.inc.php”。
2.3、类名：类名只允许有字母，数字字符和下划线，在大部分情况下不鼓励使用数字和下划线。如果类名包含多个单词，每个单词的第一个字母必须大写（“驼峰”命名规则），连续的大写是不允许的。接口类 (interface) 的定义必须遵循类名的定义规范，不同的是必须要以 _Interface 作为结尾。
注：对于类名中使用下划线，在Zend framework的编码规范中，类名中使用“_”则表示一个目录。class Db_Mysql表示该类文件存放于Db目录下，类名中多一个“_”，意味着多一个目录。对此，我们也应推荐这个类的命名规范，所以不鼓励类名中使用下划线。
2
2.4、函数名：函数名只允许由字母，数字或下划线组成，字母应当合部小写。函数名应该具有描述性，当由多个单词组成时，词语之间以单个下划线分隔（首字母要小写，其后每个单词首字母要大写，即所谓的 “camelCaps” 命名规则。此规则是允许的，为了编码有统一的规范，我们对此非常不推荐）。函数名越详细越好,名称中某处最好有一个动词。较好的函数名称如print_login_status()， get_user_data()，等等。
2.5、变量名：变量名只允许由字母和下划线组成，数字是不允许的，变量名应当全部小写，并且词语之间以单个下划线分隔（“camelCaps” 规则的变量名当然也是合法的，但非常不推荐。因为大多中国人对大小写字母混合的变量名很不习惯,《卓有成效的程序员》一书也是十分推崇下划线式的命名规则。使用下划线命名规则，也使用“camelCaps”规则，非常不利于编码规范的统一）。
例如： $current_user 是正确的， 但是 $currentuser 和 $currentUser 就不正确。 名称应当是描述性的，并且简明。禁止使用巨大的句子作为变量名。
2.6、函数参数：参数的命名原则和变量名命名的规范相同。我们不希望一堆这样的函数：do_it($a, $b, $c)。在大部分情况下，我们愿意仅仅看看函数声明就知道怎样使用它。
2.7、常量名：常量 constant 必须仅包括字母，数字和下划线，而且必须全部大写，各个单词之间用下划线分割。常量应该在类中由 const 声明并定义，全局范围内的 define 是不鼓励使用的。
2.8、PHP的内建值：英文字母统一小写(__LINE__, __FILE__等特殊内建值除外),boolean 值和 null 值统一小写（即null, false, true,而不是NULL, FALSE, TRUE）。退出关键字统一为exit(),禁用exit;
3、编程风格
3.1、代码布局：
新建文件的标准头部：这里是一个头部的模版，它应当包含在每个 DoitPHP 文件开始 /**
* 文件名 *
* 文件内容简介 * @package DoitPHP
* @author 开发者 <开发者邮箱> * @copyright Copyright (c) 发行年份
* @license New BSD License {@link http://www.doitphp.com/license/} * @version $id: 版本号 */
3.2、代码注释：
代码注释符必须用 \或者 \作为开头。\是不允许的，而 “//” 的使用仅限于函数内部。
注释风格使用phpDocumentor标准。 下面是类的注释模板 /**
* 类的作用等详细描述， *
* @package 所在的包名
3
* @author 开发者 * @version $id:版本号 */
注：至少类的详细描述不能少，@package, @author, $version可以省略。 下面是函数或类的方法注释模板 /**
* 函数名或函数的简短简介 *
* 函数内容的详细说明，描述函数的作用，用法及内部 * 操作原理等 *
* @params 参数1的数据类型 参数1 参数1的简短描述 * @params 参数2的数据类型 参数2 参数2的简短描述 * @return 返回结果的数据类型 返回结构的描述 */ 注：return 共分为boolean, string, mixed, integer, null。当没有数据返回时应是return void。 \和 \是不一样的。\意味着返回一个空的变量。而 \则表示什么都没有返回。
当或返回boolean，或返回string时，应是return boolean|string。 3.3、字符串引用（单引号与双引号）：
在 PHP 中有两种不同的方式引用字符串，使用单引号或使用双引号。主要区别是解析器在双引号括起的字符串中执行变量替换，却不在单引号括起的字符串中执行。单引号中，任何变量($var)、特殊转义字符(如“\\t \\r \\n”等)不会被解析，因此PHP的解析速度更快，转义字符仅仅支持“\\’”和“\\\\”这样对单引号和反斜杠本身的转义。因此，你应当始终使用单引号除非你明确地需要对那个字符串进行变量替换。这样，我们可以节省解析器解析一堆不需要执行替换的字符串的麻烦。同样，如果你使用字符串变量作为函数调用的一部分，你不需要用引号把那个变量括起来。同样，那样只会给解析器增加不必要的工作。无论如何，要注意几乎所有双引号中的转义序列在单引号中都不会起作用。
具体方法:
当一个字符串是纯文字组成的时候（即不含有变量），则必须总是以单引号（'）为定界符;当一个字符串含有撇号（`）的时候，我们允许使用双引号（\）来定界字符串，特别是在些 SQL 语句的时候。
注：变量替换中的变量只允许用 $+变量名 的形式。 例如：
$greeting=\允许使用 $greeting=\鼓励使用 $greeting=\不允许使用 /* 错误 */
$str = \do_it(\/* 正确 */
$str = 'This is a really long string with no variables for the parser to find.'; do_it($str);
注：在绝大多数可以使用单引号的场合，禁止使用双引号。可以或必须使用单引号的情
4
况包括但不限于下述：
(1)字符串为固定值，不包含“\\t”等特殊转义字符。 (2)数组的固定下标，例如$array[‘key’]。
(3)表达式中不需要带入变量，例如$string = ‘test’;，而非$string = “test$var”。 3.4、数组：
数组元素间要有逗号和空格隔开,便于阅读。数组的键值不推荐使用负数。 /*错误*/
$abc = array(1,2,3); /*正确*/
$abc = array(1, 2, 3); /*鼓励*/
$data_array = array( 'name'=>'streen003', 'age'=>'27', );
当数组元素为数组时，其它元素要另起一行。 $demo_array = array( array(12, 23, 35), array(33, 45, 'abc'), );
注：虽然在 PHP 中，使用一个不用引号括起来的字面上的字符串作为一个相关数组的键值是合法的。但是我们还是要求：数组中，如果下标不是整型，而是字符串类型，请务必用单引号将下标括起，正确的写法为$array[‘key’]，而不是$array[key]，因为不正确的写法会使PHP解析器认为key是一个常量，进而先判断常量是否存在，不存在时才以“key”作为下标带入表达式中，同时出发错误事件，产生一条Notice级错误。
/* 错误 */
$foo = $assoc_array[blah]; /* 正确 */
$foo = $assoc_array['blah']; 3.5、控制结构：
大括号(“{}”)：首括号与关键词同行，尾括号与关键字同列。 (1)条件语句(if,switch,三元符)： /*正确*/ if ($a > $b) {
echo $a, '大于', $b; } else {
echo $a, '不大于', $b; }
/*错误*/ if($a > $b) {
echo $a, '大于', $b; } else
5