PHP编程规范1_10(1).doc

浩宇互动（北京）科技有限公司PHP编程规范前 言为规范PHP开发的编码风格，提高开发效率和降低开发人员的时间成本，建立统一的PHP开发标准体系，依据国际、国内相关标准、法规，参照国际、国内通行的职业技能标准制定本规范。 本规范项目专家组：组的M部门本规范主要起草单位：浩宇互动（北京）科技有限公司本规范起草人：蒋文波 廖旻可修改人： 本规范于二一一年XX月XX日首次发布。适用范围 本规范规定了PHP开发当中的代码编写格式、注释及命名规则、错误及异常的处理方法、性能与安全的操作准则。确立了PHP开发工作的一般原则。针对PHP开发过程当中模糊不清的约定给出了统一明确的约定指南。本标准适用于组的 M 的PHP开发团队。1 说明1.1 必须执行必须执行的规范，用红字标明，违反相关规定每个扣0.5分，每次任务最多扣2分。1.2 参考执行参考执行的标准不强制执行只用于参考，但希望能开发人员编码风格能逐渐统一到该规范。2 代码编写格式2.1 代码标记使用来界定PHP代码。2.2 缩进PHP程序中缩进宜按标准键盘的1个“TAB”键，即4个空格为单位，一段程序中不应出现两种缩进的规则。2.3 长度a）单个函数的有效代码长度应控制在50行以内，不包括注释行。b）单个类的有效代码长度应控制在300行以内，不包括注释行。2.4 行宽每行PHP代码的行宽宜设置为80 个字符。2.5 间隔a）操作符两端应各空一个字符。 b）相应独立的功能模块之间应使用注释行间隔，并标明相应内容。 c）程序体上下之间应加入一个空白行，不应使用多空行。2.6 对齐a）关系密切的代码行应对齐，例如类型、修饰、名称、参数等。 b）连续赋值时应对齐操作符。 c）方法参数过多时应在每个参数的逗号后换行并对齐。 d）控制或循环中的条件大于行宽时，应在操作符前换行，对齐并注释相应条件。 e）变量定义应通过添加空格对齐操作符，同一类型的变量应放在一起。2.7 括号a）小括号（“( )”）使用过程中，“(”应和函数的关键词紧贴在一起，除此以外宜使用空格将“（”同前面的内容分开；右括号“）”除后面是“）”或者是“.”以外，其它内容应一律用空格隔开； b）大括号（“ ”）中的语句应单独作为一行，其中：“”应紧跟语句后；“”应单独一行与程序体第一个字符对齐，并说明相应匹配的功能模块； 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(); /声明数组 /参数对齐 3.6- getConnection($url, $user_name, $password) . /getConnection（）结束/换行对齐 3.6- $sql = SELECT * . FROM “. tname(space).” WHERE Prod_ID = . $prod_id; /条件对齐- if( Condition1 /当条件一 & Condition2 /并且条件二 | Condition3) /或者条件三 . /操作符两边空格-$result = ($a + 1) * 3 / 2 + $num).Test;$condition ? func1($var) : func2($var);?3 注释3.1 程序注释注释示例代码：/*【组的M】(C)2001-2009 Gamlaxy Inc.This is NOT a freeware, use is subject to license terms$RCSfile: forumdisplay.php,v $Revision: 1.7 $Date: 2006/02/23 13:44:02 $*/3.2 类、接口注释在类、接口定义之前，应做相应注释，包括类、接口的目的、作用、功能、继承于何种父类，实现的接口、实现的算法、使用方法、示例程序等。/* * 字符串实用类 * * 定义字符串操作时所需要用到的方法，如转换中文、HTML 标记处理等。 * * author $Author: zudemi$ * version $Revision: 1.2 $ $Date: 2003/05/15 02:10:27 $ */ public class StringUtil 类、接口注释示例代码：3.3 函数方法注释a）应明确该方法的功能、作用、各参数含义及返回值等。b）若在函数方法内注释复杂算法，应用/*.*/。c）为参数作注释时应注明取值范围和返回值，还应明确相应失败、错误、异常时的返回情况。函数方法注释示例代码：/* * 执行查询。 * 该方法调用 Statement 的 executeQuery(sql)方法并返回 ResultSet * 结果集。 * param sql 标准的 SQL 语句 * return ResultSet 结果集，若查询失败则返回 null * throws SQLException 当查询数据库时可能引发此异常 */ function execute_query($sql) /SQL 语句都不能为空 if( != $sql) /返回查询执行结果 return mysql_query($sql); return null; /end eexecute_query()3.4 其它注释程序开发中的临时代码和调试代码，应添加注释。譬如：“/debug”。程序中不应该出现调试的print,echo,var_dump等语句。3.5后期修改上的注释 在修改前人基础上的代码时，必须在修改的地方开始写上edted by xxxx 2011-2-10 start加上简单的程序修改说明，结尾地方写上 end 示例代码： / edited by jiangwb 2010-02-10 start 修改用户经验方法/ end4 命名（下划线加不加待定）(A)4.1 文件文件名应使用小写英文字母和下划线：“_”，文件名不宜出现数字，不应使用纯数字命名。可用前缀来明确文件的类别及功能，例如：class_db_mysql.php。4.2 变量变量名中所有字母宜小写。对于一个变量使用多个单词的，应使用下划线_作为每个词的间隔。例如：$base_dir、$red_rose_price等。4.3 常量常量应全部使用大写字母命名，少数特别必要的情况下，可以使用下划线来分隔单词；例如：define(A_GLOBAL_CONSTANT, Hello world!)；PHP的内建值TRUE、FALSE和NULL应全部采用大写字母书写。4.4 类、接口类和接口命名，应以大写字母开头；多个单词组成命名，单词之间不必使用间隔，各个单词首字母宜使用大写。类和接口中属性的命名方式参考本规范5.2的变量命名规范。例如：class MyClass 或class DbOracle等。4.5 方法、函数函数名应一律使用小写格式，如有必要，单词之间宜使用下划线“_”进行分割；以标准计算机英文为蓝本，可使用拼音、但拼音应该语义清晰明了，不应使用拼音英文混杂的命名方式；变量命名只能是使用项目中有据可查的英文缩写方式。譬如：宜使用$data这样的形式，而不宜使用$data1、$data2这样容易产生混淆的形式，应使用$theraddata、$postdata这样容易理解的形式。5 声明 5.1 类、接口类的划分代码块不宜太大，避免造成过于庞大的单个类。也不宜太细，避免类的继承太深。根据类的职责，应当一个类只做一件事，每个类应写在单独一个程序文件中。宜多使用设计模式，随时重构。多个类中使用相同方法时，应将其方法提到一个接口中或使用抽象类，提高复用度。5.2 方法 (B)一个方法应只完成一项功能。定义系统的公用接口方法以外的方法时，应缩小其可见性。避免用一个类的实例去访问其静态变量和方法。在一个较长的方法里不应提供多个出口。不应定义过多的参数列表，应控制在 5 个以内。方法的示例代码如下：/不要使用这钟方式，当处理程序段很长时将很难找到出口点 if($condition) return A; else return B; /建议使用如下方式 $result = null; if($condition) $result = A; else $result = B; return $result; 5.3 变量(A)任何变量在进行累加、直接显示或存储前应进行声明。例如：$number = 0; /数值类行声明$string = ;/字符串声明$array = array();/数组声明判断一个无法确定（不知道是否已被赋值）的变量时，可用empty()或isset(),不应直接使用if($switch)的形式。5.4 常量任何常量应在使用前声明，并且常量应在其他声明之前进行声明。5.5 其他(A)在程序代码中不应直接使用有特殊含义的数字及字符串。直接使用的数字或字符串时应先定义和说明。示例代码：/错误的示例/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);define(WE_GOOFED, 19);if(PRESIDENT_WENT_CRAZY = $foo) start_thermo_nuclear_war(); else if(WE_GOOFED = $foo) refund_lotso_money(); else happy_days_i_know_why_im_here(); 6 表达式与语句6.1 控制语句左大括号应与关键词同行，右大括号应与关键字同列。if结构中，else 和 elseif 与前后两个大括号同行，左右各一个空格；另外，即便if后只有一行语句，应加入大括号，以保证结构清晰。switch结构中，当一个case块处理后，应添加break。break的位置与case同在一行，或新起一行均可。同一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;6.2 循环语句在for和while的循环使用中,对于continue、break的使用,应避免导致程序流程混乱，不易理解和维护障碍。7 错误与异常7.1 已检查异常与运行时异常已检查异常应捕捉并做相应处理，不能将已检查异常抛到系统之外去处理。 对可预见的运行时异常应当进行捕捉并处理。7.2 异常错误提示设置在软件开发和调试阶段，如果使用error_reporting(E_ALL)，宜在程序文件的头几行进行设置。在软件发布时，应使用error_reporting(E_ERROR | E_WARNING | E_PARSE)作为默认的错误报告级别，利于用户使用并可将无谓错误提示出现频率降至最低。8 测试与BUG跟踪8.1 测试基本原则测试要完整并且全面，应将各种可能的情况都测试通过，将可能的 Bug 在开发中捕捉并处理掉。测试要保证可再测试性。测试应当对数据库等资源不留或少留痕迹。譬如：当测试添加一个用户时，在其成功后应及时从数据库中删除该记录，避免残余数据的产生。对关键功能应测试并通过。8.2 BUG跟踪和缺陷处理当系统出现 BUG 时，应由该 DUG 的负责人（代码负责人）尽快修改。 DUG 的处理根据其优先级高低和重要级别高低先后处理。不应隐瞒 BUG。 9 性能与安全9.1 输入与输出当程序接受输入操作时，应检查输入数据的合法性，避免造成不合法或错误的数据存入数据库或者导致意料之外的程序操作。譬如：如果程序以用户输入的参数值做为文件名，进行文件操作，恶意输入系统文件名会造成系统损毁。应核实对cookie的使用以及对用户数据的处理可能出现的问题，避免造成用户数据泄漏。9.2 SQL语句处理规则在程序接到参数需要进行SQL操作时，应对特殊符号做转义，尤其要注意分号(”;”)和单引号(“”)的使用。10 其它 包含调用程序文件，应全部使用require_once()或include_once()，以避免可能的重复包含问题。11 多语言问题在功能设计阶段，当需要使用中文或者给出用户中文提示的时候可以直接在程序中插入简体中文文字，待程序整理和测试阶段由专人进行语言分离工作；功能说明性语言、短语一般不使用“。”或者其他标点符号作为结束，文字中的标点符号，应使用全角。但注意：由于中英文模板与语言包问题，功能说明性的语言中，冒号使用半角”:”，而不使用全角；提示信息和使用技巧(如后台管理界面中的tips)等大篇幅文字中，当中的标点符号应当遵循中文语法规则，以使用全角中文标点为主，结尾应当加入全角句号。尽管程序语言包是在最后整理阶段才进行提取，但程序中直接写出的中文内容，也应充分保证书面语的特征：语言通顺、简洁、得体、无歧义。应彻底杜绝认为直接写提示语言是临时性操作的想法，反复推敲，并总结之前提示语言的特征规范，加以应用。良好的语言文字表达能力，是每个优秀程序员必须具备的基本素质之一。13数据库设计13.1 字段13.1.1表和字段命名表和字段的命名以前面5 命名的约定为基本准则。所有数据表名称，只要其名称是可数名词，则必须以复数方式命名，例如：cdb_members(用户表)、cdb_posts(帖子表)；存储多项内容的字段，或代表数量的字段，也应当以复数方式命名，例如：params(parameters，自定义Discuz!代码的参数个数)、views(查看次数)、replies(回复次数)。当几个表间的字段有关连时，要注意表与表之间关联字段命名的统一，如cdb_threads表中的tid与cdb_posts表中的tid。代表id自增量的字段，通常用以下几种形式：A. 最常用的核心id，或经常在URL中进行调用的，尽量用简写的形式，例如tid、pid、uid；B. 有功能性作用，URL中偶尔用到的id，使用全称的形式，例如pluginid；C. 没有功能性作用，只为管理和维护方便而设的id，可以使用全称的形式，也可只将其命名为id。13.1.2字段结构允许NULL值的字段，数据库在进行比较操作时，会先判断其是否为NULL，非NULL时才进行值的必对。因此基于效率的考虑，所有字段均不能为空，即全部NOT NULL；预计不会存储非负数的字段，例如各项id、发帖数等，必须设置为UNSIGNED类型。UNSIGNED类型比非UNSIGNED类型所能存储的正整数范围大一倍，因此能获得更大的数值存储空间；存储开关、选项数据的字段，通常使用tinyint(1)非UNSIGNED类型，少数情况也可能使用enum()结果集的方式。tinyint作为开关字段时，通常1为打开；0为关闭；-1为特殊数据，例如N/A(不可用)；高于1的为特殊结果或开关二进制数组合(详见Discuz!中相关代码)；MEMORY/HEAP类型的表中，要尤其注意规划节约使用存储空间，这将节约更多内存。例如cdb_sessions表中，就将IP地址的存储拆分为4个tinyint(3) UNSIGNED类型的字段，而没有采用char(15)的方式；字段的说明不能用1，2，3等数字，用英文缩写比如 comType 1公会 2 公会俱乐部应该改成comType com 公会 comclub 公会俱乐部（或者预定义1,2,3）任何类型的数据表，字段空间应当本着足够用，不浪费的原则，数值类型的字段取值范围见下表：字段类型存储空间(b)UNSIGNED取值范围tinyint1否-128127是0255smallint2否-3276832767是065535mediumint3否-83886088388607是016777215int4否-21474836482147483647是04294967295bigint8否-92233720368547758089223372036854775807是01844674407370955161513. 2 SQL语句 所有SQL语句中，除了表名、字段名称以外，全部语句和函数均需小写，应当杜绝大写方式或大小写混杂的写法。很长的SQL语句应当有适当的断行，依据JOIN、FROM、ORDER BY等关键字进行界定。通常情况下，在对多表进行操作时，要根据不同表名称，对每个表指定一个12个字母的缩写，以利于语句简洁和可读性。不容许直接在query里写sql,必须在query前赋值，再查询。如下的语句范例，是符合规范的：$sql=SELECT s.*, m.*FROM “.tname(space).”sessions s, “.tname(members).” mWHERE m.uid=s.uid AND s.sid=$sid;$query = $db-query($sql);13.3性能与效率13.3.1定长与变长表包含任何varchar、text等变长字段的数据表，即为变长表，反之则为定长表。进行表结构设计时，应当做到恰到好处，反复推敲，从而实现最优的数据存储体系。13.3.2 运算与检索数值运算一般比字符串运算更快。例如比较运算，可在单一运算中对数进行比较。而串运算涉及几个逐字节的比较，如果串更长的话，这种比较还要多。如果串列的值数目有限，应该利用普通整型或emum类型来获得数值运算的优越性。更小的字段类型永远比更大的字段类型处理要快得多。对于字符串，其处理时间与串长度直接相关。一般情况下，较小的表处理更快。对于定长表，应该选择最小的类型，只要能存储所需范围的值即可。例如，如果mediumint够用，就不要选择bigint。对于可变长类型，也仍然能够节省空间。一个TEXT 类型的值用2 字节记录值的长度，而一个LONGTEXT 则用4字节记录其值的长度。如果存储的值长度永远不会超过64KB，使用TEXT 将使每个值节省2字节。13.3.3结构优化与索引优化索引能加快查询速度，而索引优化和查询优化是相辅相成的，既可以依据查询对索引进行优化，也可以依据现有索引对查询进行优化，这取决于修改查询或索引，哪个对现有产品架构和效率的影响最小。索引优化与查询优化是多年经验积累的结晶，在此无法详述，但仍然给出几条最基本的准则。首先，根据产品的实际运行和被访问情况，找出哪些SQL语句是最常被执行的。最常被执行和最常出现在程序中是完全不同的概念。最常被执行的SQL语句，又可被划分为对大表(数据条目多的)和对小表(数据条目少的)的操作。无论大表或小表，有可分为读(SELECT)多、写(UPDATE/INSERT)多或读写都多的操作。对常被执行的SQL语句而言，对大表操作需要尤其注意：13.3.3.1可使用写入缓存的方法，先将需要写或需要更新的数据缓存至文件或其他表，定期对大表进行批量写操作，例如Discuz!中点击数延迟更新机制，就是依据此原理实现。同时，应尽量使得常被读写的大表为定长类型，即便原本的结构中大表并非定长。大表定长化，可以通过改变数据存储结构和数据读取方式，将一个大表拆成一个读写多的定长表，和一个读多写少的变长表来实现；13.3.3.2依据SQL查询频率设置专门针对高频SQL语句的索引和联合索引。而小表就相对简单，加入符合查询要求的特定索引，通常效果比较明显。同时，定长化小表也有益于效率和负载能力的提高。字段比较少的小定长表，甚至可以不需要索引。其次，看SQL语句的条件和排序字段是否动态性很高(即根据不同功能开关或属性，SQL查询条件和排序字段的变化很大的情况)，动态性过高的SQL语句是无法通过索引进行优化的。惟一的办法只有将数据缓存起来，定期更新，适用于结果对实效性要求不高的场合。MySQL索引，常用的有PRIMARY KEY、INDEX、UNIQUE几种，详情请查阅MySQL文档。通常，在单表数据值不重复的情况下，PRIMARY KEY和UNIQUE索引比INDEX更快，请酌情使用。事实上，索引是将条件查询、排序的读操作资源消耗，分布到了写操作中，索引越多，耗费磁盘空间越大，写操作越慢。因此，索引决不能盲目添加。对字段索引与否，最根本的出发点，依次仍然是SQL语句执行的概率、表的大小和写操作的频繁程度。13.3.4查询优化MySQL中并没有提供针对查询条件的优化功能，因此需要开发者在程序中对查询条件的先后顺序人工进行优化。例如如下的SQL语句：SELECT * FROM table WHERE a0 AND b0还是b1哪个条件在前，得到的结果都是一样的，但查询速度就大不相同，尤其在对大表进行操作时。开发者需要牢记这个原则：最先出现的条件，一定是过滤和排除掉更多结果的条件；第二出现的次之；以此类推。因而，表中不同字段的值的分布，对查询速度有着很大影响。而ORDER BY中的条件，只与索引有关，与条件顺序无关。除了条件顺序优化以外，针对固定或相对固定的SQL查询语句，还可以通过对索引结构进行优化，进而实现相当高的查询速度。原则是：在大多数情况下，根据WHERE条件的先后顺序和ORDER BY的排序字段的先后顺序而建立的联合索引，就是与这条SQL语句匹配的最优索引结构。尽管，事实的产品中不能只考虑一条SQL语句，也不能不考虑空间占用而建立太多的索引。同样以上面的SQL语句为例，最优的当table表的记录达到百万甚至千万级后，可以明显的看到索引优化带来的速度提升