PHP 程序编码规范

PHP 程 序 编 码 规 范 乐 邦 科 技 程 序 部 版 本 1.2

前 言 目 的 : 为 了 更 好 的 便 于 规 范 PHP 团 队 成 员 编 码 规 范, 统 一 编 码 风 格, 帮 助 大 家 更 好 的 形 成 良 好 的 编 码 风 格 适 用 范 围 : 本 规 范 权 限 于 乐 邦 科 技 程 序 部 PHP 团 队 内 部 适 用 标 准 化 作 用 : 当 一 个 项 目 尝 试 着 遵 守 公 共 一 致 的 标 准 时, 可 以 使 参 与 项 目 的 开 发 人 员 更 容 易 了 解 项 目 中 的 代 码 弄 清 程 序 的 状 况 使 新 的 参 与 者 可 以 很 快 的 适 应 环 境, 防 止 部 分 参 与 者 出 于 节 省 时 间 的 需 要, 自 创 一 套 风 格 并 养 成 终 生 的 习 惯, 导 致 其 它 人 在 阅 读 时 浪 费 过 多 的 时 间 和 精 力, 而 且 在 一 致 的 环 境 下, 也 可 以 减 少 编 码 出 错 的 机 会 缺 陷 是 由 于 每 个 人 的 标 准 不 同, 所 以 需 要 一 段 时 间 来 适 应 和 改 变 自 己 的 编 码 风 格, 暂 时 性 的 降 底 了 工 作 效 率 从 使 项 目 长 远 健 康 的 发 展 以 及 后 期 更 高 的 团 队 工 作 效 率 来 考 虑 暂 时 的 工 作 效 率 降 低 是 值 得 的, 也 是 必 须 要 经 过 的 一 个 过 程 标 准 不 是 项 目 成 功 的 关 键, 但 可 以 帮 助 我 们 在 团 队 协 作 中 有 更 高 的 效 率 并 且 更 加 顺 利 的 完 成 即 定 的 任 务 1. 程 序 员 可 以 了 解 任 何 代 码, 弄 清 程 序 的 状 况 2. 新 人 可 以 很 快 的 适 应 环 境 3. 防 止 新 接 触 PHP 的 开 发 出 于 节 省 时 间 的 需 要, 自 创 一 套 风 格 并 养 成 终 生 的 习 惯 4. 防 止 新 接 触 PHP 的 开 发 一 次 次 的 犯 同 样 的 错 误 5. 在 一 致 的 环 境 下, 可 以 减 少 犯 错 的 机 会

PHP 编 码 规 范 一 基 本 规 范 1. 文 件 格 式 1.1. 标 签 PHP 代 码 的 编 码 格 式 使 用 不 带 字 节 顺 序 标 记 (BOM) 的 UTF-8 1.2. 编 码 PHP 代 码 使 用 长 标 签 (<?php?>) 或 者 短 输 出 式 标 签 (<?=?>), 而 不 可 使 用 其 他 标 签 2. 命 名 规 则 2.1. 概 述 常 用 命 名 规 范 : Pascal 命 名 规 则 ( 帕 斯 卡 ) 将 标 识 符 的 每 个 单 词 的 首 字 母 都 大 写 例 如 :BackColor Camel 命 名 规 则 ( 骆 驼 式 ) 将 标 识 符 的 首 字 母 小 写, 而 后 面 链 接 的 单 词 的 首 字 司 都 大 写 例 如 :backcolor Linux C 命 名 规 则 将 所 有 字 母 都 使 用 小 写, 使 用 _ 作 为 每 个 词 的 分 界 命 名 必 须 有 一 定 的 意 义, 并 且 意 义 准 确 : 例 如 : 有 一 个 变 量 用 于 保 存 图 书 的 数 目, 可 以 命 名 为 mumber_of_book 或 者 num_of_book 不 建 议 使 用 i,j,n 等, 因 为 它 没 有 意 义, 也 不 建 议 使 用 number 或 book, 因 为 意 义 不 准 确

2.2. 文 件 命 名 类 的 文 件 的 名 称 与 类 的 名 称 保 持 一 致, 使 用 Pascal 命 名 法 如 类 IndexAction, 对 应 的 文 件 名 称 为 IndexAction.php 视 图 文 件 命 名 使 用 驼 峰 命 名 方 式, 如 indexaction.php 配 置 文 件 名 称 全 部 小 写, 如 :config.php 类 库 文 件, 助 手 文 件 和 模 型 文 件 命 名 与 类 文 件 命 名 方 式 保 持 一 致 2.3. 类 命 名 类 名 命 名 方 式 使 用 Pascal 命 名 方 法, 类 名 应 该 和 文 件 名 保 持 一 致 2.4. 接 口 命 名 接 口 命 名 方 式 同 类 命 名 方 式 一 致, 习 惯 上 名 字 前 面 加 上 大 写 的 I 2.5. 函 数 命 名 函 数 命 名 方 式 一 般 为 一 个 动 词 或 者 行 为 动 词, 使 用 驼 峰 命 名 方 式 命 名, 例 如 : Function getexecutiontime(), 私 有 函 数 命 名 使 用 以 _ 开 头 注 意 : 尽 量 使 用 有 意 义 描 述 性 单 词 来 命 名 函 数 名, 避 免 使 用 单 个 字 母 来 命 名 函 数 名 常 用 的 命 名 前 缀 : Is - 询 问 get - 获 取 set - 设 置 num - 数 量

2.6. 变 量 命 名 变 量 命 名 尽 量 使 用 有 意 义 的 描 述 性 词 来 命 名 变 量, 统 一 使 用 驼 峰 命 名 法 来 命 名 变 量 避 免 使 用 一 些 没 有 意 义 的 缩 写 避 免 使 用 单 个 字 母 来 命 名 变 量 2.7. 常 量 命 名 常 量 命 名 统 一 全 部 使 用 大 写 字 母 和 下 划 线 来 命 名, 不 能 使 用 小 写 字 母 3. 注 释 规 则 3.1. 一 般 注 释 单 行 注 释 : 在 语 句 结 束 后 用 // 解 释 该 语 句 的 具 体 作 用, // 后 加 一 个 空 格, 例 如 : 多 行 注 释 : 使 用 /* 开 始, 并 以 */ 结 束, 用 于 标 注 多 行 语 句 的 具 体 作 用 ( 开 始 结 束 符 各 占 一 行 ) 3.2. 版 权 注 释 文 件 开 头 使 用 // 来 标 示 版 权 信 息, 以 免 和 PHPDocumentor 和 page-level DocBlock 发 生 冲 突, 例 如 :

3.3. 类 注 释 类 声 明 时 要 在 头 部 注 明 类 作 用 作 者 等, 例 如 : 或 3.4. 方 法 / 函 数 注 释 方 法 声 明 时 要 在 开 头 说 明 其 实 现 功 能 各 参 数 返 回 值 意 义, 复 杂 逻 辑 要 在 声 明 时 说 明 其 实 现 思 想, 并 在 关 键 步 骤 做 出 注 释 调 用 方 法 时 也 要 指 出 其 目 的, 例 如 :

4. 其 它 4.1. 副 作 用 一 个 源 文 件 建 议 只 用 来 做 声 明 ( 类, 函 数, 常 量 等 ) 或 者 只 用 来 做 一 些 引 起 副 作 用 的 操 作 ( 例 如 : 输 出 信 息, 修 改.ini 配 置 等 ), 但 不 建 议 同 时 做 这 两 件 事 副 作 用 (side effects) 包 含 但 不 局 限 于 : 产 生 输 出, 显 式 地 使 用 require 或 include, 连 接 外 部 服 务, 修 改 ini 配 置, 触 发 错 误 或 异 常, 修 改 全 局 或 者 静 态 变 量, 读 取 或 修 改 文 件 等 等 下 面 是 一 个 既 包 含 声 明 又 有 副 作 用 的 示 例 文 件 ; 即 应 避 免 的 例 子 : 下 面 是 一 个 仅 包 含 声 明 的 示 例 文 件 ; 即 应 提 倡 的 例 子 :

4.2. 命 名 空 间 和 类 建 议 一 个 源 文 件 中 只 能 有 一 个 类 (class), 并 且 每 个 类 (class) 至 少 要 有 一 级 空 间 名 (namespace): 即 一 个 顶 级 的 组 织 名 (vendor name) 类 名 (class name) 必 须 使 用 Pascal 写 法 PHP5.3 之 后 的 代 码 必 须 使 用 正 式 的 命 名 空 间 (namespace) 例 子 : PHP5.2.x 之 前 的 代 码 建 议 用 伪 命 名 空 间 Vendor_ 作 为 类 名 (class name) 的 前 缀

二 风 格 规 范 1. 基 本 风 格 这 个 示 例 中 简 单 展 示 了 文 中 提 到 的 一 些 规 则 : 2. 通 用 规 则 2.1. 源 文 件 所 有 的 PHP 源 文 件 必 须 使 用 Unix LF( 换 行 ) 作 为 行 结 束 符 所 有 PHP 源 文 件 必 须 以 一 个 空 行 结 束 纯 PHP 代 码 源 文 件 的 关 闭 标 签?> 必 须 省 略

2.2. 行 行 长 度 不 可 有 硬 限 制 行 长 度 的 软 限 制 必 须 是 120 个 字 符 ; 对 于 软 限 制, 代 码 风 格 检 查 器 须 警 告 但 不 可 报 错 一 行 代 码 的 长 度 不 建 议 超 过 80 个 字 符 ; 较 长 的 行 建 议 拆 分 成 多 个 不 超 过 80 个 字 符 的 子 行 在 非 空 行 后 面 不 可 有 空 格 空 行 可 以 用 来 增 强 可 读 性 和 区 分 相 关 代 码 块 一 行 不 可 多 于 一 个 语 句 2.3. 缩 进 代 码 必 须 使 用 4 个 半 角 空 格, 且 不 可 使 用 制 表 符 来 作 为 缩 进 注 意 : 代 码 中 只 使 用 空 格, 且 不 和 制 表 符 混 合 使 用, 将 会 对 避 免 代 码 差 异, 补 丁, 历 史 和 注 解 中 的 一 些 问 题 有 帮 助 空 格 的 使 用 还 可 以 使 通 过 调 整 细 微 的 缩 进 来 改 进 行 间 对 齐 变 得 更 加 的 简 单 2.4. 关 键 字 和 true/false/null PHP 关 键 字 (keywords) 必 须 使 用 小 写 字 母 PHP 常 量 true, false 和 null 必 须 使 用 小 写 字 母 3. 命 名 空 间 和 导 入 声 明 命 名 空 间 (namespace) 的 声 明 后 面 必 须 有 一 行 空 行 所 有 的 导 入 (use) 声 明 必 须 放 在 命 名 空 间 (namespace) 声 明 的 下 面 一 句 声 明 中, 必 须 只 有 一 个 导 入 (use) 关 键 字 在 导 入 (use) 声 明 代 码 块 后 面 必 须 有 一 行 空 行 如 示 例 :

4. 类 属 性 和 方 法 4.1. 扩 展 (extend) 和 实 现 (implement) 一 个 类 的 扩 展 (extend) 和 实 现 (implement) 关 键 词 必 须 和 类 名 (class name) 在 同 一 行 类 (class) 的 左 花 括 号 必 须 放 在 下 面 自 成 一 行 ; 右 花 括 号 必 须 放 在 类 (class) 主 体 的 后 面 自 成 一 行 实 现 (implement) 列 表 可 以 被 拆 分 为 多 个 缩 进 了 一 次 的 子 行 如 果 要 拆 成 多 个 子 行, 列 表 的 第 一 项 必 须 要 放 在 下 一 行, 并 且 每 行 必 须 只 有 一 个 接 口 (interface)

4.2. 属 性 (property) 所 有 的 属 性 (property) 都 必 须 声 明 其 可 见 性 变 量 (var) 关 键 字 不 可 用 来 声 明 一 个 属 性 (property) 一 条 语 句 不 可 声 明 多 个 属 性 (property) 属 性 名 不 推 荐 用 单 个 下 划 线 作 为 前 缀 来 表 明 其 保 护 (protected) 或 私 有 (private) 的 可 见 性 一 个 属 性 (property) 声 明 看 起 来 应 该 像 下 面 这 样 4.3. 方 法 (method) 所 有 的 方 法 (method) 都 必 须 声 明 其 可 见 性 方 法 名 不 推 荐 用 单 个 下 划 线 作 为 前 缀 来 表 明 其 保 护 (protected) 或 私 有 (private) 的 可 见 性 方 法 名 (method name) 在 其 声 明 后 面 不 可 有 空 格 跟 随 其 左 花 括 号 必 须 放 在 下 面 自 成 一 行, 且 右 花 括 号 必 须 放 在 方 法 主 体 的 下 面 自 成 一 行 左 括 号 后 面 不 可 有 空 格, 且 右 括 号 前 面 也 不 可 有 空 格 一 个 方 法 (method) 声 明 看 来 应 该 像 下 面 这 样 注 意 括 号, 逗 号, 空 格 和 花 括 号 的 位 置 :

4.4. 方 法 (method) 的 参 数 在 参 数 列 表 中, 逗 号 之 前 不 可 有 空 格, 而 逗 号 之 后 则 必 须 要 有 一 个 空 格 方 法 (method) 中 有 默 认 值 的 参 数 必 须 放 在 参 数 列 表 的 最 后 面 参 数 列 表 可 以 被 拆 分 为 多 个 缩 进 了 一 次 的 子 行 如 果 要 拆 分 成 多 个 子 行, 参 数 列 表 的 第 一 项 必 须 放 在 下 一 行, 并 且 每 行 必 须 只 有 一 个 参 数 当 参 数 列 表 被 拆 分 成 多 个 子 行, 右 括 号 和 左 花 括 号 之 间 必 须 又 一 个 空 格 并 且 自 成 一 行 4.5. 抽 象 (abstract), 终 结 (final) 和 静 态 (static) 当 用 到 抽 象 (abstract) 和 终 结 (final) 来 做 类 声 明 时, 它 们 必 须 放 在 可 见 性 声 明 的 前 面 而 当 用 到 静 态 (static) 来 做 类 声 明 时, 则 必 须 放 在 可 见 性 声 明 的 后 面

4.6. 调 用 方 法 和 函 数 调 用 一 个 方 法 或 函 数 时, 在 方 法 名 或 者 函 数 名 和 左 括 号 之 间 不 可 有 空 格, 左 括 号 之 后 不 可 有 空 格, 右 括 号 之 前 也 不 可 有 空 格 参 数 列 表 中, 逗 号 之 前 不 可 有 空 格, 逗 号 之 后 则 必 须 有 一 个 空 格 参 数 列 表 可 以 被 拆 分 成 多 个 缩 进 了 一 次 的 子 行 如 果 拆 分 成 子 行, 列 表 中 的 第 一 项 必 须 放 在 下 一 行, 并 且 每 一 行 必 须 只 能 有 一 个 参 数 5. 控 制 结 构 5.1. 概 述 下 面 是 对 于 控 制 结 构 代 码 风 格 的 概 括 : 控 制 结 构 的 关 键 词 之 后 必 须 有 一 个 空 格

控 制 结 构 的 左 括 号 之 后 不 可 有 空 格 控 制 结 构 的 右 括 号 之 前 不 可 有 空 格 控 制 结 构 的 右 括 号 和 左 花 括 号 之 间 必 须 有 一 个 空 格 控 制 结 构 的 代 码 主 体 必 须 进 行 一 次 缩 进 控 制 结 构 的 右 花 括 号 必 须 主 体 的 下 一 行 每 个 控 制 结 构 的 代 码 主 体 必 须 被 括 在 花 括 号 里 这 样 可 是 使 代 码 看 上 去 更 加 标 准 化, 并 且 加 入 新 代 码 的 时 候 还 可 以 因 此 而 减 少 引 入 错 误 的 可 能 性 5.2. if,elseif,else 下 面 是 一 个 if 条 件 控 制 结 构 的 示 例, 注 意 其 中 括 号, 空 格 和 花 括 号 的 位 置 同 时 注 意 else 和 elseif 要 和 前 一 个 条 件 控 制 结 构 的 右 花 括 号 在 同 一 行 推 荐 用 elseif 来 替 代 else if, 以 保 持 所 有 的 条 件 控 制 关 键 字 看 起 来 像 是 一 个 单 词 5.3. switch,case 下 面 是 一 个 switch 条 件 控 制 结 构 的 示 例, 注 意 其 中 括 号, 空 格 和 花 括 号 的 位 置 case 语 句 必 须 要 缩 进 一 级, 而 break 关 键 字 ( 或 其 他 中 止 关 键 字 ) 必 须 和 case 结 构 的 代 码 主 体 在 同 一 个 缩 进 层 级 如 果 一 个 有 主 体 代 码 的 case 结 构 故 意 的 继 续 向 下 执 行 则 必 须 要 有 一 个 类 似 于 // no break 的 注 释

5.4. while,do while 下 面 是 一 个 while 循 环 控 制 结 构 的 示 例, 注 意 其 中 括 号, 空 格 和 花 括 号 的 位 置 下 面 是 一 个 do while 循 环 控 制 结 构 的 示 例, 注 意 其 中 括 号, 空 格 和 花 括 号 的 位 置 5.5. for 下 面 是 一 个 for 循 环 控 制 结 构 的 示 例, 注 意 其 中 括 号, 空 格 和 花 括 号 的 位 置

5.6. foreach 下 面 是 一 个 foreach 循 环 控 制 结 构 的 示 例, 注 意 其 中 括 号, 空 格 和 花 括 号 的 位 置 5.7. try, catch 下 面 是 一 个 try catch 异 常 处 理 控 制 结 构 的 示 例, 注 意 其 中 括 号, 空 格 和 花 括 号 的 位 置 6. 闭 包 声 明 闭 包 时 所 用 的 function 关 键 字 之 后 必 须 要 有 一 个 空 格, 而 use 关 键 字 的 前 后 都 要 有 一 个 空 格 闭 包 的 左 花 括 号 必 须 跟 其 在 同 一 行, 而 右 花 括 号 必 须 在 闭 包 主 体 的 下 一 行 闭 包 的 参 数 列 表 和 变 量 列 表 的 左 括 号 后 面 不 可 有 空 格, 右 括 号 的 前 面 也 不 可 有 空 格 闭 包 的 参 数 列 表 和 变 量 列 表 中 逗 号 前 面 不 可 有 空 格, 而 逗 号 后 面 则 必 须 有 空 格 闭 包 的 参 数 列 表 中 带 默 认 值 的 参 数 必 须 放 在 参 数 列 表 的 结 尾 部 分 下 面 是 一 个 闭 包 的 示 例 注 意 括 号, 空 格 和 花 括 号 的 位 置

参 数 列 表 和 变 量 列 表 可 以 被 拆 分 成 多 个 缩 进 了 一 级 的 子 行 如 果 要 拆 分 成 多 个 子 行, 列 表 中 的 第 一 项 必 须 放 在 下 一 行, 并 且 每 一 行 必 须 只 放 一 个 参 数 或 变 量 当 列 表 ( 不 管 是 参 数 还 是 变 量 ) 最 终 被 拆 分 成 多 个 子 行, 右 括 号 和 左 花 括 号 之 间 必 须 要 有 一 个 空 格 并 且 自 成 一 行 下 面 是 一 个 参 数 列 表 和 变 量 列 表 被 拆 分 成 多 个 子 行 的 示 例

把 闭 包 作 为 一 个 参 数 在 函 数 或 者 方 法 中 调 用 时, 依 然 要 遵 守 上 述 规 则

三 其 它 规 范 1. 补 充 说 明 本 规 范 参 考 于 FIG 组 织, 规 范 中 有 意 的 省 略 了 许 多 元 素 的 代 码 风 格 主 要 包 括 : 全 局 变 量 和 全 局 常 量 的 声 明 函 数 声 明 操 作 符 和 赋 值 行 间 对 齐 注 释 和 文 档 块 类 名 的 前 缀 和 后 缀 以 上 的 代 码 规 范 中 可 能 会 修 正 或 扩 展 本 文 中 规 定 的 代 码 风 格