QC质量管理体系文件代码编写规范受控状态:■受控□非受控发布日期:2006年02月20日实施日期:2006年02月24日代码编写规范第1页代码编写规范文件编号1.0版共4页(含本页)编制PHP开发组审核批准编制日期2006.02.24审核日期批准日期实施日期修改日期文件会签表部门名称会签人/日期主要责任部门软件开发部赵晨淋/2006-02-23相关责任部门文件修改记录修改单号修改页码修改人批准人生效日期代码编写规范第2页1.引言1.1.目的制定本规范是为了能达到以下目的:提高程序员工作效率和代码的利用性程序员可以了解任何代码,弄清程序的状况新人可以很快的适应环境防止新接触php的人出于节省时间的需要,自创一套风格并养成终生的习惯防止新接触php的人一次次的犯同样的错误在一致的环境下,人们可以减少犯错的机会1.2.适用范围适用于本公司的所有开发人员,包括数据库、网页及应用程序开发人员,及有关的程序测试人员。1.3.引用标准GB/T8566-1995信息技术软件生存期过程GB/T8567-1988计算机软件产品开发文件编写指南1.4.术语GB/T11457-1995中所使用的术语适用于本规范。代码编写规范第3页2.代码编写规则2.1.注释(1)编写代码期间注释要求占程序总量15%以上。(2)每个模块顶部必须说明模块名称、功能描述、作者等。(3)每个过程、函数、方法等开头部分必须说明功能、参数、返回值、原数据和目标数据数据结构等等。(4)变量定义的行末应当对变量给出注释。(5)程序在实现关键算法的地方应当给出注释2.2.变量、函数、过程、控件等命名规则(1)变量命名采用[作用范围][数据类型][自定义名称]规则定义,要求看到变量名就能直观的看出其范围和数据类型。(2)函数、过程、方法、事件等命名应尽量做到观其名知其义。(3)控件的命名采用[控件类型][自定义名]规则定义,要求通过名字能直观看出控件类型。(4)自定义命名空间规则,要求能顾名思义2.3.源代码规则风格约定:采用缩进的格式保存程序的层次结构。要求能直观的看出循环、判断等层次结构。代码编写规范第4页2.4.用户界面规范(1)用户界面布局和结构应当合理。(2)颜色搭配方面应当咨询美术专业人员。(3)界面中必须有产品标识,如果在用户许可情况下可加入公司标识。2.5.合理性原则(1)提示说明应当简短且避免产生歧义。(2)提示或警告信息应当具有向导性,能准确告诉用户错误原因及恢复方法。提示和警告对话框应当使用标准规范。(3)快捷键的定义必须符合用户操作习惯(4)程序需要长时间处理或等待时,应当显示进度条并提示用户等待。(5)一些敏感操作,如删除等操作在执行前必须提示用户确认。代码编写规范第5页3.命名规则一般原则:命名要与其自然想适合,根据名字能推导出其含义,一般人的推想也能在意料之中。3.1.目录和文件的命名原则:通过名称就能理解目录或文件的意义。规则:(1)目录命名使用英文小写字母,长度不超过20个字符;(2)文件命名用小写的英文字母、数字和下划线的组合;(3)文件名称使用“性质_描述”的规则,描述可以有多个单词,用”_”隔开,性质一般是该页面得概要。如register_form.php;(4)凡是类文件使用“模块名_controller.php”的形式,如admin_controller.php。3.2.类(class)命名原则:通过类名就能想起这个类是什么。规则:(1)词的首字母大写,其它字母一概小写;(2)多个词组成的混合名,使用大写字母作为词的分隔,其它字母小写,用以真正传送信息;(3)不要使用下划线“_”;(4)缩写词不要全部使用大写字母。如使用GetHtmlStatistic,而不用GetHTMLStatistic;(5)派生类的命名与父类无关,只与自身有关。3.3.函数和方法命名原则:通常每个函数和方法都是执行一个动作,所以其命名要清楚地说明它们是做什么的。代码编写规范第6页规则:(1)采用“动作_动作对象”或者简单的就直接使用“动作”的形式.(2)例子形式1:get_table_name()形式2:add()3.4.类属性命名规则:(1)所有字母都使用小写;(2)使用“_”作为每个词的分界;(3)例如:$associations$many_to_many_sql3.5.方法中参数命名规则:采用和类属性命名相同的命名规则;3.6.变量命名规则:(1)所有字母都使用小写;(2)使用“_”作为每个词的分界;(3)如$error,$time_of_error;(4)临时变量的取名应加上前缀tmp,如tmp_user_ame;(5)对象变量的取名应加上前缀obj_作为前缀,如:obj_user;(6)数组变量的取名应加上前缀arr,如arr_book_name;(7)数组下标的变量类型可以是整型和字符串型两种;1.若为整形,数组下标不要用双引号包含;2.若为字符串型,必须用双引号包含。代码编写规范第7页3.7.其它(1)用变量和函数返回引用时,引用必须带‘r’前缀(2)全局变量应该带前缀“g”(3)定义命名/全局常量时,全局常量所有字母大写,用“_”分隔每个单词,如:define(“A_GLOBAL_CONSTANT”,”helloworld”)(4)静态变量应该带前缀“s”,如:static$sStatus=0;代码编写规范第8页4.书写规则4.1.IFELSE语句[布局]if(条件1){//注释}elseif(条件2){//注释}else{//注释}如果有用elseif语句,要有一个else块以用于处理未处理到的其他情况,可以的话放一个记录信息注释在else处,即使else没有任何的动作。[条件格式]总是将恒量放在等号/不等号的左边,如:if(6==$errorNum)…4.2.SWITCH格式(1)一个case块处理后,直接转到下一个case块处理,在这个case块的最后应该加上注释;(2)defaultcase总应该存在,它应该不被到达,然而如果到达了就会触发一个错误;(3)如果要创立一个变量,那就把所有的代码放在块中。4.3.Continue,Break和?:的使用(1)不鼓励使用Continue和Break;(2)?:把条件放在括号内以使它和其它的代码相分离;动作尽可能用简单的函数;把所做动作,“?”,“:”放在不同的行。代码编写规范第9页4.4.布尔逻辑类型大部分函数在FALSE的时候返回0,但是返回非0值就代表TRUE,因而不要用1(TRUE,YES,诸如此类)等式检测一个布尔值,应该用0(FALSE,NO,诸如此类)的不等式来代替:if(TRUE==func()){...应该写成:if(FALSE!=func()){...4.5.大括号{}规则将大括号放置在关键词同一行,距前面字符一个空格:if($condition){}4.6.缩进/制表符/空格规则(1)缩进采用键盘Tab键,不采用空格键。并且”=”或者链接字符串时需要左右空一格,每层次缩进长度为4个半角空格;(2)缩进层次大于四或五级,可考虑将代码因数分解(factoringoutcode)。4.7.小括号/关键词/函数规则(3)不要把小括号和关键词紧贴在一起,要用空格隔开;(4)小括号和函数名紧贴在一起;(5)除非必要,不要在return返回语句中使用小括号。(6)永远不要在括号与括号之间的字符中间留下空格;(7)永远不要在一个语句中使用不必要的括号,括号只应在源代码中需要的地方使用;(8)不要把小括号和关键词紧贴在一起,要用空格隔开;(9)要把小括号和函数名紧贴在一起,以免跟关键字相混;代码编写规范第10页4.8.php文件扩展名(10)所有浏览者可见页面使用“.htm”;(11)所有类、函数库文件使用“.php”4.9.不要不可思议的数字用define()来给想表示某样东西的数值一个真正的名字,而不是采用赤裸裸的数字,如:define(“PRESIDENT_WENT_CRAZY”,”22”);define(“WE_GOOFED”,“19”);4.10.关于$_GET等变量的调用规则(1)所有GET、POST、SESSION、COOKIE、SERVER等变量均不能直接调用;(2)GET变量ss要使用$_GET[“ss”]调用;(3)POST变量ss要使用$_POST[“ss”]调用;(4)COOKIE变量ss要使用$_COOKIE[“ss”]调用;(5)SESSION变量ss要使用$_SESSION[“ss”]调用;(6)SERVER变量ss要使用$_SERVER[“ss”]调用;4.11.其它(1)别在对象架构期做实际的工作(2)记录所有空语句(3)不要采用缺省方法测试非零值(4)通常避免采用嵌入式的赋值(5)每行一个语句(6)短方法,方法代码要限制在一页内4.12.代码编辑器(1)需统一使用风格类似的编辑器(2)建议使用ZendStudio代码编写规范第11页5.书写注释一般原则:1、程序中的注释应该能够被PHPDocument工具转换。2、鼓励使用非文档注释。一般性规则是对于那些容易忘记作用的代码添加简短的介绍性注释。3、使用C样式的注释(/**/)和标准C++注释(//),而不使用Perl/shell样式的注释(#)。5.1.文件头注释在每个源文件的头部要有必要的注释信息,包括:文件名;版本号;作者;修改历史;生成日期;模块功能描述(如功能、主要算法、内部各部分之间的关系、该文件与其它文件关系等);主要函数或过程清单及本文件历史修改记录等。注释方法:/***简述**(详细的功能描述)**@author*@version*@history*/5.2.函数头注释在每个函数或过程的前面要有必要的注释信息,包括:函数或过程名称;功能描述;输入、输出及返回值说明;调用关系及被调用关系说明等。注释方法:根据实际情况采用单行注释(//)或多行注释(/**/)。5.3.行注释在以下地方需要加上注释:(1)代码中重要部分或难度较大部分加注释;代码编写规范第12页(2)在if、else语句中具有暗示意味、有重要意义的条件旁加注释;(3)当循环语句中的终止条件不太清晰时加注释;(4)代码复杂部分加注释;(5)容易引起混乱的变量加注释。(6)需要添加但未实现的代码模块;注释方法:(1)//注释一行(2)////四个斜杠代表当前有未实现的内容,相当于占位符(3)/*……*/注释若干行(4)注释简单明了,含义准确,防止注释二义性。保持注释与其描述的代码相邻,即注释的就近原则;(5)边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性;(6)变量、常量的注释应放在其上方相邻位置或右方;(7)全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时的注意事项等;5.4.其它(1)PHP脚本标记采用?php…?,只输出变量时用?phpecho$username;?;(2)无论在什么地方无条件包含一个类型文件,应该使用require_once();有条件的包含一个类型文件,应该使用include_once()。(3)在HTML网页中尽量不要穿插PHP代码,循环代码和纯粹变量输出除外;(4)保证代码和文档的一致性;(5)和大家保持沟通,有问题随时提出,避免走弯路和重复他人已做过的工作;(6)SQL代码布局:既然我们都在使用不同的编辑器设置,不要尝试去做诸如在SQL代码中实现列对齐此类的麻烦事。要做的是,不管用何种方法,把语句断行到它们单独的行上去。这里有一个SQL代码看上去应该是什么样子的示例。注意在哪里断行,大写,和括号的用法。例如:SELECTfield1ASsomething,field2,field3FROMtablea,tablebWHERE(this=that)AND(this2=that2)