1、PHP 编程规范(试行)前言为规范 PHP 开发编码风格,提高开发效率和减少开发人员时间成本,建立统一 PHP 开 发原则体系,根据国际、国内有关原则、法规,参照国际、国内通行职业技能原则制定本规范。本规范由大连市经济和信息化委员会提出并归口。 本规范项目召集单位: 本规范项目专家组:本规范重要起草单位:本规范起草人: 本规范于二一年十一月四日初次发布。目录1.适用范围32.定义和术语32.1 PHP 语言32.2 程序代码33.代码编写格式33.1 代码标记33.2 缩进33.3 长度43.4 行宽43.5 间隔43.6 对齐43.7 括号44.注释54.1 预注释54.2 类、接口注释64
2、.3 函数方法注释64.5 其它注释75.命名75.1 文件75.2 变量85.3 常量85.4 类、接口85.5 方法、函数86.声明86.1 类、接口86.2 方法86.3 变量96.4 常量96.5 其他97.表达式与语句107.1 控制语句107.2 循环语句118.错误与异常118.1 已检查异常与运行时异常118.2 异常错误提示设置119.测试与 BUG 跟踪119.1 测试基本原则119.2 BUG 跟踪和缺陷处理1110.性能与安全1210.1 输入与输出1210.2 针对 PHP.INI 的规则1210.3 SQL 语句处理规则1211.其它1212. 附录1212.1 注
3、释模板12PHP 编程规范1.合用范畴本规范规定了 PHP 开发当中代码编写格式、注释及命名规则、错误及异常解决办法、性能与安全操作准则。确立了 PHP 开发工作普通原则。针对 PHP 开发过程当中模糊不清 商定给出了统一明确商定指南。本原则合用于从事 PHP 开发有关公司、开发团队、教诲和培训服务机构以及有关决策等 机构,针对 PHP 开发工作进行商定、检查、鉴定以及针对 PHP 开发人员技术培训。2.定义和术语2.1 PHP 语言PHP 是基于服务端应用和创立动态网页多用途脚本语言,可嵌入 HTML,并支持主流数 据库和操作系统。2.2 程序代码程序代码是一系列计算机系统可以辨认,人类可读
4、具备特定含义计算机语言字符集 合。3.代码编写格式3.1 代码标记PHP 程序可以使用或来界定 PHP 代码,在 HTML 页面中嵌入纯变量时, 可以使用这样形式。3.2 缩进PHP 程序中缩进宜按原则键盘 1 个“TAB”键,即 4 个空格为单位,一段程序中不应出 现两种缩进规则。3.3 长度a)单个函数有效代码长度应控制在 100 行以内,不涉及注释行。b)单个类有效代码长度应控制在 1500 行以内,不涉及注释行。3.4 行宽每行 PHP 代码行宽宜设立为 80 个字符。3.5 间隔a)操作符两端应各空一种字符。 b)相应独立功能模块之间应使用注释行间隔,并标明相应内容。 c)程序体上下
5、之间应加入一种空白行,不应使用多空行。3.6 对齐a)关系密切代码行应对齐,例如类型、修饰、名称、参数等。b)持续赋值时应对齐操作符。 c)办法参数过多时应在每个参数逗号后换行并对齐。 d)控制或循环中条件不不大于行宽时,应在操作符前换行,对齐并注释相应条件。 e)变量定义应通过添加空格对齐操作符,同一类型变量应放在一起。3.7 括号a)小括号(“( )”)使用过程中,“(”应和函数核心词紧贴在一起,除此以外宜使用空 格将“(”同前面内容分开;右括号“)”除背面是“)”或者是“.”以外,其他内容应一律用 空格隔开;b)大括号(“ ”)中语句应单独作为一行,其中: “”应紧跟语句后; “”应单独
6、一行与程序体第一种字符对齐,并阐明相应匹配功能模块;c)较长办法以及类、接口等后应使用/end .等标记结束。例如: 类结束符:/EOC ClassName,办法结束符:/end methodName(), 功能块结束:/end if.userName is null?循环体结束:/end for.every user in userList 示例:?Php /代码标记 3.1/缩进 3.2- for($i = 0;$i 0)$n = $i;/变量对齐 3.6-$count= 100;$length= 0;$user_name = null;$porduct= array();/声明数组/参数
7、对齐 3.6- getConnection($url,$user_name,$password). /getConnection()结束/换行对齐 3.6-$sql = SELECT * . FROM TProduct WHERE Prod_ID = .$prod_id;/条件对齐- if( Condition1/当条件一& Condition2/并且条件二| Condition3) /或者条件三./操作符两边空格-$result = ($a + 1) * 3 / 2 + $num).Test;$condition ?func1($var) :func2($var);?4.注释4.1 预注释预
8、注释中,应涉及程序名称、程序版本及修订版本号、CVS(版本控制系统)控制字符串、更新时间等信息内容。在预注释中,宜放入相应 CVS 控制字串,以以便 CVS 提交时自动更 新。宜采用多行注释方式。预注释示例代码:/*开发组名称和版权声明等$RCSfile:forumdisplay.php,v $Revision:1.75$Date:/02/23 13:44:02$*/4.2 类、接口注释在类、接口定义之前,应做相应注释,涉及类、接口目、作用、功能、继承于何种父 类,实现接口、实现算法、用法、示例程序等。类、接口注释示例代码:/* 字符串实用类* 定义字符串操作时所需要用到办法,如转换中文、HT
9、ML 标记解决等。* author $Author:l_walker$* version $Revision:1.2 $ $Date:/05/15 02:10:27 $*/public class StringUtil4.3 函数办法注释a)应明确该办法功能、作用、各参数含义及返回值等。 b)若在函数办法内注释复杂算法,应用/*.*/。 c)为参数作注释时应注明取值范畴和返回值,还应明确相应失败、错误、异常时返回状况。 函数办法注释示例代码:/* 执行查询。* 该办法调用 Statement executeQuery(sql)办法并返回 ResultSet* 成果集。* param sql 原
10、则 SQL 语句* return ResultSet 成果集,若查询失败则返回 null* throws SQLException 当查询数据库时也许引起此异常*/function execute_query($sql) /SQL 语句都不能为空if( != $sql)/返回查询执行成果return mysql_query($sql);return null;/end eexecute_query()4.5 其他注释程序开发中暂时代码和调试代码,应添加注释。譬如:“/debug”。 其他注释示例代码:$num= 1;$flag = TURE;/debug if(empty($flag). /S
11、tatements5.命名5.1 文献文献名应使用小写英文字母和下划线:“_”,文献名不适当浮现数字,不应使用纯数字命名。 可用前缀来明确文献类别及功能,例如:class_db_mysql.php。5.2 变量变量名中所有字母宜小写。对于一种变量使用各种单词,应使用下划线_作为每个词 间隔。例如:$base_dir、$red_rose_price 等。5.3 常量常量应所有使用大写字母命名,少数特别必要状况下,可以使用下划线来分隔单词;例 如:define(A_GLOBAL_CONSTANT,Hello world!);PHP 内建值 TRUE、FALSE 和 NULL应所有采用大写字母书写。
12、5.4 类、接口类和接口命名,应以大写字母开头;各种单词构成命名,单词之间不必使用间隔,各个单 词首字母宜使用大写。类和接口中属性命名方式参照本规范 5.2 变量命名规范。例如:class MyClass 或 class DbOracle 等。5.5 办法、函数函数名应一律使用小写格式,如有必要,单词之间宜使用下划线“_”进行分割;以原则计 算机英文为蓝本,可使用拼音、但拼音应当语义清晰明了,不应使用拼音英文混杂命名方式; 变量命名只能是使用项目中有据可查英文缩写方式。譬如:宜使用$data 这样形式,而不适当 使用$data1、$data2 这样容易产生混淆形式,应使用$theraddata
13、、$postdata 这样容易理解形 式。6.声明6.1 类、接口类划分代码块不适当太大,避免导致过于庞大单个类。也不适当太细,避免类继承太深。 依照类职责,应当一种类只做一件事,每个类应写在单独一种程序文献中。宜多使用设计模 式,随时重构。各种类中使用相似办法时,应将其办法提到一种接口中或使用抽象类,提高复 用度。6.2 办法一种办法应只完毕一项功能。定义系统公用接口办法以外办法时,应缩小其可见性。 避免用一种类实例去访问其静态变量和办法。在一种较长办法里不应提供各种出口。不应 定义过多参数列表,应控制在 5 个以内。办法示例代码如下:/不要使用这钟方式,当解决程序段很长时将很难找到出口点i
14、f($condition)return A;elsereturn B;/建议使用如下方式$result = null;if($condition)$result = A;else$result = B;return $result;6.3 变量任何变量在进行累加、直接显示或存储前应进行声明。 例如:$number = 0;/数值类行声明$string = ;/字符串声明$array = array(); /数组声明判断一种无法拟定(不懂得与否已被赋值)变量时,可用 empty()或 isset(),不应直接使用if($switch)形式。6.4 常量任何常量应在使用前声明,并且常量应在其她声明
15、之迈进行声明。6.5 其她在程序代码中不应直接使用有特殊含义数字及字符串。直接使用数字或字符串时应先 定义和阐明。示例代码:/错误示例/22和19 这样数字,很难懂得它含义,导致理解上困难。if (22 = $foo)start_thermo_nuclear_war();else if (19 = $foo)refund_lotso_money();else cry_cause_im_lost();/对的示例代码。/应当用define()来给你想表达某样东西数值一种真正名字,/而不应直接采用数字,这样代码阅读起来清晰明了。 define(PRESIDENT_WENT_CRAZY,22);def
16、ine(WE_GOOFED,19);if(PRESIDENT_WENT_CRAZY = $foo)start_thermo_nuclear_war();else if(WE_GOOFED = $foo)refund_lotso_money();7.表达式与语句7.1 控制语句左大括号应与核心词同行,右大括号应与核心字同列。if 构造中,else 和 elseif 与先后两个大括号同行,左右各一种空格;此外,即便 if 后只有一行语句,应加入大括号,以保证构造清晰。switch 构造中,当一种 case 块解决后,应添加 break。break 位置与 case 同在一行,或 新起一行均可。同一
17、 switch 体中,break 位置格式应当保持一致。控制语句示例代码:if($condition)switch($var)case 1:echo var is 1;break;case 2:echo var is 2;break;default:echo var is neither 1 or 2;break;elseif($condition)switch($str)case abc;$result = abc;break;default:$result = unknown;break;elseecho unknown;7.2 循环语句在 for 和 while 循环使用中,对于 con
18、tinue、break 使用,应避免导致程序流程混乱, 不易理解和维护障碍。8.错误与异常8.1 已检查异常与运营时异常已检查异常应捕获并做相应解决,不能将已检查异常抛到系统之外去解决。 对可预见运 行时异常应当进行捕获并解决。8.2 异常错误提示设立在软件开发和调试阶段,如果使用 error_reporting(E_ALL),宜在程序文献头几行进行 设立。在软件发布时,应使用 error_reporting(E_ERROR | E_WARNING | E_PARSE)作为默认错 误报告级别,利于顾客使用并可将无谓错误提示浮现频率降至最低。9.测试与 BUG 跟踪9.1 测试基本原则测试要完整
19、并且全面,应将各种也许状况都测试通过,将也许 Bug 在开发中捕获并处 理掉。测试要保证可再测试性。测试应当对数据库等资源不留或少留痕迹。譬如:当测试添加一种顾客时,在其成功后应 及时从数据库中删除该记录,避免残存数据产生。对核心功能应测试并通过。9.2 BUG 跟踪和缺陷解决当系统浮现 BUG 时,应由该 DUG 负责人(代码负责人)尽快修改。 DUG 解决根 据其优先级高低和重要级别高低先后解决。不应隐瞒 BUG。10.性能与安全10.1 输入与输出当程序接受输入操作时,应检查输入数据合法性,避免导致不合法或错误数据存入数 据库或者导致意料之外程序操作。譬如:如果程序以顾客输入参数值做为文
20、献名,进行文 件操作,恶意输入系统文献名会导致系统损毁。应核算对 cookie 使用以及对顾客数据解决也许浮现问题,避免导致顾客数据泄漏。10.2 针对 PHP.INI 规则设立 register_globals = off10.3 SQL 语句解决规则在程序接到参数需要进行 SQL 操作时,应对特殊符号做转义,特别要注意分号(”;”)和单 引号(“”)使用。11.其他包括调用程序文献,应所有使用 require_once()或 include_once(),以避免也许重复包括问 题。12. 附录12.1 注释模板?php/* vim:set expandtab tabstop=4 softt
21、abstop=4 shiftwidth=4:*/ +-+/ | PHP version 4|/ +-+/ | Copyright (c) 1997- The PHP Group|/ +-+/ | This source file is subject to version 2.0 of the PHP license,|/ | that is bundled with this package in the file LICENSE,and is|/ | available at through the world-wide-web at|/ | |/ | If you did not receive a copy of the PHP license and are unable to|/ | obtain it through the world-wide-web,please send a note to|/ | so we can mail you a copy immediately.|/ +-+/ | Authors:Original Author |/ | Your Name |/ +-+/ $ Id $?