[计算机]php编码规范.doc

第 1 页 共 9 页 编码规范编码规范 编码规范编码规范1 1.引言引言.1 2.适用范围适用范围.2 3.标准化的重要性和好处标准化的重要性和好处.2 4.PHP 编码规范与原则编码规范与原则2 4.1.代码标记.2 4.2.注释.2 4.3.书写规则.3 4.3.1.缩进3 4.3.2.大括号、if和switch.3 4.3.3.运算符、小括号、空格、关键词和函数4 4.3.4.函数定义5 4.3.5.引号6 4.4.命名原则.6 4.4.1.变量、对象、函数名7 4.4.2.常量7 4.5.变量的初始化与逻辑检查.7 4.6.安全性.8 4.7.兼容性.8 4.8.代码重用.8 4.9.其他细节问题.9 4.9.1.错误报告级别9 1. 引言引言 本规范由编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好 一致的编程风格。以达到事半功倍的效果，如果有需要本文档会不定期更新。 第 2 页 共 9 页 2. 适用范围适用范围 Php 项目开发。 3. 标准化的重要性和好处标准化的重要性和好处 当一个软件项目尝试着遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的 代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要， 自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下， 也可以减少编码出错的机会。缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的 编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑 暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助 我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。 1. 程序员可以了解任何代码，弄清程序的状况程序员可以了解任何代码，弄清程序的状况 2. 新人可以很快的适应环境新人可以很快的适应环境 3. 防止新接触防止新接触 PHP 的人出于节省时间的需要，自创一套风格并养成终生的习惯的人出于节省时间的需要，自创一套风格并养成终生的习惯 4. 防止新接触防止新接触 PHP 的人一次次的犯同样的错误的人一次次的犯同样的错误 5. 在一致的环境下，人们可以减少犯错的机会在一致的环境下，人们可以减少犯错的机会 6. 程序员们有了一致的敌人程序员们有了一致的敌人 4. PHP 编码规范与原则编码规范与原则 4.1.代码标记代码标记 PHP 程序可以使用或来界定 PHP 代码，在 HTML 页面中嵌入纯变量时，可以使 用这样的形式。 近年来 PHP 开发组一直倡导代码规范化和标准化，未来版本 PHP 可能会开始不建议使用甚至取消 和这种速记形式，届时本文档也将进行跟进修改。 4.2.注释注释 注释是对于那些容易忘记作用的代码添加简短的介绍性内容。请使用 C 样式的注释“/* */”和 标准 C+ 注释“/” 。 在 Discuz!每一个程序文件头部中，应放入相应 CVS 控制字串，以方便 CVS 提交时自动更新： 第 3 页 共 9 页 $RCSfile$程序文件名 $Revision$修订版本号 $Date$最后更新时间 例如： /* DODI (C)2001-2006 Comsenz 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 $ */ 程序开发中难免留下一些临时代码和调试代码，此类代码必须添加注释，以免日后遗忘。所有临 时性、调试性、试验性的代码，必须添加统一的注释标记“/debug”并后跟完整的注释信息，这样 可以方便在程序发布和最终调试前批量检查程序中是否还存在有疑问的代码。例如： $num = 1; $flag = TRUE; /debug 这里不能确定是否需要对这里不能确定是否需要对$flag 进行赋值进行赋值 if(empty($flag) /Statements 4.3.书写规则书写规则 4.3.1. 缩进缩进 每个缩进的单位约定是一个每个缩进的单位约定是一个 TAB(8 个空白字符宽度个空白字符宽度)，需每个参与项目的开发人员在编辑器 (UltraEdit、EditPlus、Zend Studio 等)中进行强制设定，以防在编写代码时遗忘而造成格式 上的不规范。 本缩进规范适用于 PHP、JavaScript 中的函数、类、逻辑结构、循环等。 4.3.2. 大括号大括号、if 和和 switch 首括号与关键词同行，尾括号与关键字同列； if 结构中，else 和 elseif 与前后两个大括号同行，左右各一个空格。另外，即便 if 后只有 一行语句，仍然需要加入大括号，以保证结构清晰； 第 4 页 共 9 页 switch 结构中，通常当一个 case 块处理后，将跳过之后的 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; else switch($str) case abc: $result = abc; break; default: $result = unknown; break; 4.3.3. 运算符、小括号、空格、关键词和函数运算符、小括号、空格、关键词和函数 每个运算符与两边参与运算的值或表达式中间要有一个空格，唯一的特例是字符连接运算符号两 边不加空格； 左括号“(” 应和函数关键词紧贴在一起，除此以外应当使用空格将“(”同前面内容分开； 右括号“)”除后面是“)”或者“.”以外，其他一律用空格隔开它们； 除字符串中特意需要，一般情况下，在程序以及 HTML 中不出现两个连续的空格； 任何情况下，PHP 程序中不能出现空白的带有 TAB 或空格的行，即：这类空白行应当不包含任何 TAB 或空格。同时，任何程序行尾也不能出现多余的 TAB 或空格。多数编辑器具有自动去除行尾空格 的功能，如果习惯养成不好，可临时使用它，避免多余空格产生； 每段较大的程序体，上、下应当加入空白行，两个程序块之间只使用 1 个空行，禁止使用多行。 程序块划分尽量合理，过大或者过小的分割都会影响他人对代码的阅读和理解。一般可以以较大 函数定义、逻辑结构、功能结构来进行划分。少于 15 行的程序块，可不加上下空白行； 说明或显示部分中，内容如含有中文、数字、英文单词混杂，应当在数字或者英文单词的前后加 入空格。 第 5 页 共 9 页 根据上述原则，以下举例说明正确的书写格式： $result = ($a + 1) * 3 / 2 + $num).Test; $condition ? func1($var) : func2($var); $condition ? $long_statement : $another_long_statement; if($flag) /Statements /More than 15 lines Showmessage(请使用请使用 restore.php 工具恢复数据。工具恢复数据。 ); 4.3.4. 函数定义函数定义 参数的名字和变量的命名规范一致； 函数定义中的左小括号，与函数名紧挨，中间无需空格； 开始的左大括号与函数定义为同一行，中间加一个空格，不要另起一行； 具有默认值的参数应该位于参数列表的后面； 函数调用与定义的时候参数与参数之间加入一个空格； 必须仔细检查并切实杜绝函数起始缩进位置与结束缩进位置不同的现象。 例如，符合标准的定义： function authcode($string, $operation, $key = ) if($flag) /Statement /函数体函数体 不符合标准的定义： function authcode($string,$operation,$key = ) /函数体函数体 第 6 页 共 9 页 4.3.5. 引号引号 PHP 中单引号和双引号具有不同的含义，最大的几项区别如下： 单引号中，任何变量($var)、特殊转义字符(如“t r n”等)不会被解析，因此 PHP 的解 析速度更快，转义字符仅仅支持“ ”和“”这样对单引号和反斜杠本身的转义； 双引号中，变量($var)值会代入字符串中，特殊转义字符也会被解析成特定的单个字符，还有一 些专门针对上述两项特性的特殊功能性转义，例如“$”和“$arraykey。这样虽然程序编 写更加方便，但同时 PHP 的解析也很慢； 数组中，如果下标不是整型，而是字符串类型，请务必用单引号将下标括起，正确的写法为 $arraykey，而不是$arraykey，因为不正确的写法会使 PHP 解析器认为 key 是一个常量， 进而先判断常量是否存在，不存在时才以“key”作为下标带入表达式中，同时出发错误事件，产生一 条 Notice 级错误。 因此，在绝大多数可以使用单引号的场合，禁止使用双引号在绝大多数可以使用单引号的场合，禁止使用双引号。依据上述分析，可以或必须使用单 引号的情况包括但不限于下述： 字符串为固定值，不包含“t”等特殊转义字符； 数组的固定下标，例如$arraykey； 表达式中不需要带入变量，例如$string = test;，而非$string = “test$var” ； 例外的，在正则表达式(用于 preg_系列函数和 ereg 系列函数)中，Discuz!全部使用双引号， 这是为了人工分析和编写的方便，并保持正则表达式的统一，减少不必要的分析混淆。 数据库 SQL 语句中，所有数据必须加单引号，无论数值还是字串，以避免可能的注入漏洞和 SQL 错误。正确的写法为： UPDATE cdb_members SET adminid=1 WHERE username=$admin AND adminid=2; 所有数据在插入数据库之前，均需要进行 addslashes()处理，以免特殊字符未经转义在插入数 据库的时候出现错误。Discuz!中如果已经引入了文件 common.inc.php，则所有通过 GET, POST, FILE,取得的变量默认情况下已经使用了 addslashes()进行了转义，不必重复进行。如果 数据处理必要(例如用于直接显示)，可以使用 stripslashes() 恢复，但数据在插入数据库之前必 须再次进行转义。 缓存文件中，一般对缓存数据的值采用 addcslashes($string, )进行转义。 4.4.命名原则命名原则 命名是程序规划的核心。古人相信只要知道一个人真正的名字就会获得凌驾于那个人之上的不可 思议的力量。只要你给事物想到正确的名字，就会给你以及后来的人带来比代码更强的力量。 名字就是事物在它所处的生态环境中一个长久而深远的结果。总的来说，只有了解系统的程序员 第 7 页 共 9 页 才能为系统取出最合适的名字。如果所有的命名都与其自然相适合，则关系清晰，含义可以推导得出， 一般人的推想也能在意料之中。 就一般约定而言，类、函数和变量的名字应该总是能够描述让代码阅读者能够容易的知道这些代 码的作用。形式越简单、越有规则，就越容易让人感知和理解。应该避免使用模棱两可，晦涩不标准 的命名。 4.4.1. 变量、对象、函数名变量、对象、函数名 变量、对象、函数名一律为小写格式，除非必要，单词之间一般不使用下划线“_”进行分割； 以标准计算机英文为蓝本，杜绝一切拼音、或拼音英文混杂的命名方式； 变量命名只能使用项目中有据可查的英文缩写方式，例如可以使用$data 而不可使用 $data1、$data2 这样容易产生混淆的形式，应当使用$threaddata、$postdata 这样一目了然容 易理解的形式； 可以合理的对过长的命名进行缩写，例如$bio($biography)，$tpp($threadsPerPage)， 前提是英文中有这样既有的缩写形式，或字母符合英文缩写规范； 必须清楚所使用英文单词的词性，在权限相关的范围内，大多使用$allow*或$is*的形式， 前者后面接动词，后者后面接形容词。 4.4.2. 常量常量 常量应该总是全部使用大写字母命名，少数特别必要的情况下，可使用划线来分隔单词； PHP 的内建值 TRUE、FALSE 和 NULL 必须全部采用大写字母书写。 4.5.变量的初始化与逻辑检查变量的初始化与逻辑检查 任何变量在进行累加、直接显示或存储前必需进行初使化任何变量在进行累加、直接显示或存储前必需进行初使化，例如： $number = 0; /数值型初始化数值型初始化 $string = ; /字符串初始化字符串初始化 $array = array(); /数组初始化数组初始化 判断一个无法确定（不知道是否已被赋值）的变量时，可用 empty()或 isset()，而不要直接 使用 if($switch)的形式，除非你确切的知道此变量一定已经被初始化并赋值。 empty()和和 isset()的区别为：的区别为： bool empty(mixed var) 如果 var 是非空或非零的值，则 empty() 返回 FALSE。换句话说， “、0、“0“、NULL、FALSE、array()、var $var; 以及没有任何属性的对象都将 第 8 页 共 9 页 被认为是空的，如果 var 为空，则返回 TRUE。 bool isset(mixed var, mixed var, .) 如果 var 存在则返回 TRUE，否则返回 FALSE。 如果已经使用 unset() 释放了一个变量之后，它将不再是 isset()。若使用 isset() 测试一个被设置成 NULL 的变量，将返回 FALSE。同时要注意的是一个 NULL 字节（“0“）并不等同于 PHP 的 NULL 常数。 判断一个变量是否为数组，请使用 is_array()，这种判断尤其适用于对数组进行遍历的操作， 例如 foreach()，因为如果不事先判断，foreach()会对非数组类型的变量报错； 判断一个数组元素是否存在，可使用 isset($arraykey)，也可使用 empty()，两者异同 见上。 4.6.安全性安全性 PHP 中的变量不并不像 C 语言那样需要事先声明，解释器会在第一次使用时自动创建他们，同样 类型也不需要指定，解释器会根据上下文环境自动确定。从开发人员的角度来看，这无疑是一种极其 方便的处理方法。一个变量被创建了，就可以在程序中的任何地方使用。这导致的结果就是开发人员 工经常不注意初始化变量。因此，为了提高程序的安全性，我们不能相信任何没有明确定义的变量。 所有的变量在定义使用前要初使化以防止恶意构造提交的变量覆盖程序中使用的变量。 细节可以阅读（.au/studyinscarlet.txt）这篇文档， 该文档里罗列了 PHP 常见的安全问题，阅读该文档是非常有必要的！ 4.7.兼容性兼容性 代码设计应当兼顾 PHP 高低版本的特性，当前，应仍然以 PHP 4.0.6 作为最低通过平台，尽量 不使用高版本 PHP 新增的函数、常数或者常量。如果使用只在高版本才具备的函数，必须对其进行二 次封装，自动判断当前 PHP 版本，并自行编写低版本下的兼容代码； 对于个别函数，参数要求或者代码要求应当以较为严格的 PHP 版本为准； 除非必要，不要使用 PHP 扩展模块中的函数。使用时应当加入必要的判断，当服务器环境不支持 此函数的时候，进行必要的处理。文档和程序中的功能说明中，也应加上兼容性说明。 4.8.代码重用代码重用 代码的有效重用可以减少效率的损失与资源的浪费。在开发软件项目时为了避免重复劳动和浪费 时间。开发人员应尽量提高现有代码的重用率，同时将更多的精力用在新技术的应用和新功能的创新 开发上面。 在需要多次使用代码，并且对于您希望实现的任务没有可用的内置