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