PHP代码编写规范

QC 质质量量管管理理体体系系文文件件 代代码码编编写写规规范范 受控状态 受受控控 非非受受控控 发布日期 2 20 00 06 6 年年 0 02 2 月月 2 20 0 日日 实施日期 2 20 00 06 6 年年 0 02 2 月月 2 24 4 日日 代码编写规范 第 1 页 代代码码编编写写规规范范 文件编号1 0 版版共共 4 页 含本页 页 含本页 编 制PHP 开发组审 核批 准 编制日期2006 02 24审核日期批准日期 实施日期修改日期 文 件 会 签 表 部门名称会签人 日期 主要责任部门软件开发部赵晨淋 2006 02 23 相关责任部门 文 件 修 改 记 录 修改单号修改页码修改人批准人生效日期 代码编写规范 第 2 页 1 引言引言 1 1 目的目的 制定本规范是为了能达到以下目的 提高程序员工作效率和代码的利用性 程序员可以了解任何代码 弄清程序的状况 新人可以很快的适应环境 防止新接触 php 的人出于节省时间的需要 自创一套风格并养成终生的习惯 防止新接触 php 的人一次次的犯同样的错误 在一致的环境下 人们可以减少犯错的机会 1 2 适用范围适用范围 适用于本公司的所有开发人员 包括数据库 网页及应用程序开发人员 及有 关的程序测试人员 1 3 引用标准引用标准 GB T 8566 1995信息技术 软件生存期过程 GB T 8567 1988计算机软件产品开发文件编写指南 1 4 术语术语 GB T 11457 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 sql 3 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 hello world 4 静态变量应该带前缀 s 如 static sStatus 0 代码编写规范 第 8 页 4 书写规则书写规则 4 1 IF ELSE 语句语句 布局 if 条件 1 注释 else if 条件 2 注释 else 注释 如果有用 else if 语句 要有一个 else 块以用于处理未处理到的其他情况 可以的话放 一个记录信息注释在 else 处 即使 else 没有任何的动作 条件格式 总是将恒量放在等号总是将恒量放在等号 不等号的左边 如 不等号的左边 如 ifif 6 errorNum 6 errorNum 4 2 SWITCH 格式格式 1 一个 case 块处理后 直接转到下一个 case 块处理 在这个 case 块的最后应该加 上注释 2 default case 总应该存在 它应该不被到达 然而如果到达了就会触发一个错误 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 缩进层次大于四或五级 可考虑将代码因数分解 factoring out code 4 7 小括号小括号 关键词关键词 函数函数 规则规则 3 不要把小括号和关键词紧贴在一起 要用空格隔开 4 小括号和函数名紧贴在一起 5 除非必要 不要在 return 返回语句中使用小括号 6 永远不要在括号与括号之间的字符中间留下空格 7 永远不要在一个语句中使用不必要的括号 括号只应在源代码中需要的地方使用 8 不要把小括号和关键词紧贴在一起 要用空格隔开 9 要把小括号和函数名紧贴在一起 以免跟关键字相混 代码编写规范 第 10 页 4 8 php 文件扩展名文件扩展名 10 所有浏览者可见页面使用 htm htm 11 所有类 函数库文件使用 php 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 建议使用 Zend Studio 代码编写规范 第 11 页 5 书写注释书写注释 一般原则 1 程序中的注释应该能够被 PHPDocument 工具转换 2 鼓励使用非文档注释 一般性规则是对于那些容易忘记作用的代码添加简短的介绍性注释 3 使用 C 样式的注释 和标准 C 注释 而不使用 Perl shell 样式的注释 5 1 文件头注释文件头注释 在每个源文件的头部要有必要的注释信息 包括 文件名 版本号 作者 修改历史 生成日期 模块功能描述 如功能 主要算法 内部各部分之间的关系 该文件与其它文件关 系等 主要函数或过程清单及本文件历史修改记录等 注释方法 简述 详细的功能描述 author version history 5 2 函数头注释函数头注释 在每个函数或过程的前面要有必要的注释信息 包括 函数或过程名称 功能描述 输入 输出及返回值说明 调用关系及被调用关系说明等 注释方法 根据实际情况采用单行注释 或多行注释 5 3 行注释行注释 在以下地方需要加上注释 代码编写规范 第 12 页 1 代码中重要部分或难度较大部分加注释 2 在 if else 语句中具有暗示意味 有重要意义的条件旁加注释 3 当循环语句中的终止条件不太清晰时加注释 4 代码复杂部分加注释 5 容易引起混乱的变量加注释 6 需要添加但未实现的代码模块 注释方法 1 注释一行 2 四个斜杠代表当前有未实现的内容 相当于占位符 3 注释若干行 4 注释简单明了 含义准确 防止注释二义性 保持注释与其描述的代码相邻 即 注释的就近原则 5 边写代码边注释 修改代码同时修改相应的注释 以保证注释与代码的一致性 6 变量 常量的注释应放在其上方相邻位置或右方 7 全局变量要有较详细的注释 包括对其功能 取值范围 哪些函数或过程存取它 以及存取时的注意事项等 5 4 其它其它 1 PHP 脚本标记采用 只输出变量时用 2 无论在什么地方无条件包含一个类型文件 应该使用 require once 有条件的包 含一个类型文件 应该使用 include once 3 在 HTML 网页中尽量不要穿插 PHP 代码 循环代码和纯粹变量输出除外 4 保证代码和文档的一致性 5 和大家保持沟通 有问题随时提出