源程序文档化

软 件 工 程 研 讨源 程 序 文 档 化第 六 组组 员 ：12122208 陈 帅12123298 马 敏12123249 雷 晴12123256 邱 可 艺2014.12.16 变 量 、 常 量 和 函 数 的 命 名 规 范 变 量 名 所 有 字 母 小 写 ， 单 词 之 间 用 下 划 线 (_)分 开 ， 类 成 员 变量 以 下 划 线 结 束 。普 通 变 量 命 名 (Common Variable Names)比 如 ：类 数 据 组 成 变 量 命 名 (Class Data Members)数 据 成 员 （ 又 叫 实 例 变 量 或 者 成 员 变 量 ） 的 命 名 与 普 通 变 量 一 样 ，全 部 字 母 小 写 ， 可 选 的 下 划 线 分 隔 符 ， 但 应 该 以 下 划 线 结 束 。 string table_name_; / 可 以 以 下 划 线 结 束string tablename_; / 可 以 变 量 命 名 (Variable Names)string table_name; / 可 以 使 用 下 划 线string tablename; / 可 以 全 部 字 母 小 写string tableName; / 糟 糕 大 小 写 混 合 结 构 体 成 员 变 量 命 名 (Struct Variables)结 构 体 成 员 变 量 和 普 通 变 量 命 名 规 则 一 致 ， 且 不 像 类成 员 变 量 以 下 划 线 结 束 。struct UrlTableProperties string name; int num_entries;全 局 变 量 命 名 (Global Variables)全 局 变 量 的 使 用 较 为 罕 见 ， 但 当 用 到 时 ，考 虑 以 前 缀 g_开 头 或 标 以 其 他 记 号 ， 以 便 与 局 部 变 量 区 分 。 常 量 命 名 (Constant Names)K后 跟 混 合 大 小 写 的 名 称 ： kDaysInAWeek。 所 有 编 译 时 常 量 ，不 管 是 被 声 明 为 局 部 、 全 局 还 是 作 为 类 的 成 员 ， 都 应 该 遵 守与 其 他 变 量 命 名 有 轻 微 差 别 的 命 名 约 定 ： k后 跟 单 词 首 字 母大 写 的 名 称 ：const int kDaysInAWeek = 7; 函 数 命 名 (Function Names)正 规 函 数 名 应 该 以 大 写 字 母 开 头 ， 单 词 首 字 母 大 写 ， 不 使 用 下划 线 。 如 果 函 数 可 能 因 错 误 而 崩 溃 ， 应 该 在 函 数 名 后 加 上OrDie。 这 仅 适 用 于 那 些 被 产 品 代 码 调 用 或 者 正 常 操 作 有 可 能引 起 错 误 的 函 数 。AddTableEntry()DeleteUrl()OpenFileOrDie() 访 问 器 和 修 改 器 (Accessors and Mutators)访 问 器 和 修 改 器 （ get和 set函 数 ） 应 该 与 它 们 关 联 的 变 量 名 匹配 。 下 面 显 示 了 一 个 类 的 部 分 摘 录 ， 它 有 一 个 实 例 变 量num_entriesclass MyClass public:.int num_entries() constreturn num_entries;void set_num_entries(int num_entries)num_entries = num_entries;private: int num_entries_; 你 也 可 以 使 用 小 写 字 母 和 下 划 线 来 命 名 非 常 短 小 的 内 联 函 数 。比 如 ， 如 果 一 个 函 数 的 调 用 开 销 很 小 ， 在 循 环 调 用 时 ， 没 必要 缓 存 其 值 ， 这 时 ， 小 写 字 母 命 名 是 允 许 的 。 对 文 件 、 类 、 函 数 、 变 量 和 逻辑 功 能 段 进 行 注 释 的 规 范 文 件 注 释 (File Comments)每 个 文 件 都 应 该 提 供 版 权 信 息 ， 然 后 是 文 件 内 容 的 综 合 性 描 述 。合 法 公 告 和 作 者 信 息 行 (Legal Notice and Author Line)每 个 文 件 都 应 依 次 包 括 以 下 条 目 ，1、 版 权 声 明 (比 如 Copyright 2008 Google Inc.)；2、 一 个 许 可 引 用 。 选 择 适 合 你 项 目 使 用 的 许 可 引 用 （ 比 如Apache 2.0、 BSD、 LGPL、 GPL）3、 作 者 信 息 行 说 明 文 件 原 始 作 者如 果 你 对 原 始 作 者 的 文 件 做 了 实 质 性 修 改 ， 可 以 在 作 者 信 息 行 加 上你 的 名 字 。 当 其 他 开 发 者 有 问 题 时 ， 这 样 可 以 方 便 他 们 正 确 地 联 系到 修 改 者 。 文 件 内 容 注 释 (File Contents)每 个 文 件 都 应 该 在 其 版 权 信 息 及 作 者 信 息 后 面 和 内 容 前 面 有一 个 内 容 描 述 性 的 注 释 。通 常 ， 头 文 件 描 述 它 所 声 明 的 类 的 目 的 及 用 法 。 而 源 文 件 则应 该 包 含 更 多 有 关 实 现 和 技 巧 性 算 法 的 讨 论 信 息 。 但 如 果 你觉 得 这 些 信 息 对 于 头 文 件 的 阅 读 者 更 有 用 ， 可 以 将 其 放 在 头文 件 中 ， 但 在 源 文 件 中 应 该 注 明 其 文 档 在 头 文 件 中 。 不 要 在头 文 件 和 源 文 件 中 重 复 注 释 ， 这 样 容 易 造 成 歧 义 。 类 注 释 (Class Comments)每 个 类 定 义 都 应 该 伴 随 有 说 明 其 目 的 和 用 法 的 注 释 。/ 遍 历GargantuanTable的 内 容 。 用 法 示 例 ：/ GargantuanTableIterator* iter = table-NewIterator();/ for(iter-seek(“foo”);!iter-done();iter-next()/ process(iter-key(),iter-value();/ / delete iter;Class GargantuanTableIterator. 如 果 你 在 文 件 开 始 就 已 对 类 进 行 了 详 细 描 述 ， 可 以 在 类 实 现部 分 简 单 地 声 明 “ 参 见 文 件 开 始 注 释 部 分 的 完 整 描 述 ” ， 但注 意 ， 这 里 还 是 要 添 加 少 量 注 释 。 函 数 注 释 (Function Comments)函 数 声 明 部 分 的 注 释 描 述 函 数 的 用 法 ， 实 现 部 分 的 注 释 描 述函 数 实 现 的 操 作 。每 个 函 数 声 明 的 前 面 都 应 该 有 一 个 描 述 函 数 功 能 和 用 法 的 注释 。 这 些 注 释 应 该 是 描 述 性 (Opens the file)， 而 不 是 祈 使 性的 （ Open the file） ， 注 释 仅 仅 描 述 函 数 能 够 完 成 什 么 功 能而 不 是 函 数 是 怎 么 实 现 的 ， 这 些 应 该 在 函 数 实 现 的 注 释 中 。在 函 数 声 明 注 释 中 应 该 提 到 的 信 息 类 型 ：1、 输 入 和 输 出 ；2、 对 于 类 成 员 函 数 ， 在 该 方 法 的 调 用 周 期 外 ， 对 象 是 否 有引 用 参 数 ， 它 是 否 会 释 放 这 些 引 用 ；3、 如 果 一 个 函 数 申 请 了 内 存 ， 它 必 须 释 放 它 们 ；4、 参 数 是 否 可 以 是 空 ； 5、 函 数 的 使 用 方 法 是 否 会 影 响 其 性 能 ；6、 如 果 函 数 可 重 入 。 它 是 怎 么 实 现 同 步 的 ？ 例 子 ：/ 返 回 这 个 表 的 一 个 迭 代 器/ 当 遍 历 结 束 时 ， 由 客 户 程 序 负 责 迭 代 器 的 释 放/ 一 旦 此 迭 代 器 的 创 建 者GargantuanTable对 象 被 释 放/ 客 户 程 序 不 可 再 使 用 此 迭 代 器/ 迭 代 器 被 初 始 化 为 指 向 表 的 开 始/ 这 个 方 法 等 价 于 ：/ Iterator *iter = table-NewIterator();iter-seek(“”);return iter;/ 如 果 你 想 立 即 寻 找 返 回 的 迭 代 器 中 的 另 一 个 位 置 ， 使 用NewIterator()更 快 ， 而/ 且 避 免 了 额 外 的 查 找 。Iterator* getIterator()const然 而 ， 避 免 不 必 要 的 冗 长 注 释 且 不 要 添 加 显 而 易 见 的 注 释 。 比如 下 例 外 中 ， 返 回 假 的 情 况 就 没 必 要 ， 因 为 这 很 明 显 ： / 如 果 表 已 被 占 满 ， 不 能 再 容 纳 实 体 ， 则 返 回 真bool IsTableFull(); 当 给 构 造 和 析 构 函 数 加 注 释 时 ， 注 意 ， 读 者 清 楚 地 知 道 这 些 函数 的 作 用 ， 所 以 诸 如 “ 销 毁 这 个 对 象 ” 的 注 释 毫 无 意 义 。 注 释内 容 应 该 说 明 构 造 函 数 怎 样 处 理 参 数 （ 比 如 它 是 否 取 得 指 针 的控 制 权 ） 和 析 构 函 数 怎 么 完 成 清 理 工 作 。 如 果 这 些 不 很 重 要 ，可 以 省 略 它 们 。 文 件 的 开 头 注 释 中 没 有 关 于 析 构 函 数 的 注 释 是很 正 常 的 。函 数 定 义 注 释 (Function Definition)每 个 函 数 都 应 该 有 一 个 注 释 来 描 述 函 数 的 功 能 和 其 完 成 这 些 功能 的 实 现 技 巧 （ 如 果 有 的 话 ） 。 比 如 ， 你 在 函 数 定 义 注 释 中 ，你 可 以 描 述 编 码 中 用 到 的 技 巧 ， 给 出 大 致 的 执 行 步 骤 或 者 解 释一 下 你 选 择 这 种 实 现 而 不 使 用 其 他 替 代 方 法 的 原 因 。 比 如 ， 你可 能 需 要 说 明 为 什 么 函 数 前 半 部 分 需 要 锁 而 后 半 部 分 不 需 要 。注 意 ， 不 能 简 单 地 重 复 头 文 件 或 者 其 他 地 方 函 数 声 明 部 分 的 注释 。 可 以 再 次 概 括 一 下 函 数 的 功 能 ， 但 焦 点 应 该 是 函 数 是 怎 么 实 现 功 能 的 。 变 量 注 释 (Variable Comments)通 常 ， 一 个 变 量 的 实 际 名 称 已 经 提 供 了 足 够 和 描 述 信 息 来 说 明其 用 途 。 但 某 些 情 况 下 ， 可 能 需 要 更 多 注 释 。类 数 据 成 员 (Class Data Members)每 个 类 数 据 成 员 （ 也 称 实 例 变 量 或 者 成 员 变 量 ） 应 该 有 一 个 描述 其 用 途 的 注 释 。 如 果 这 个 变 量 能 取 得 具 有 特 殊 意 义 的 标 志 值 ，比 如 NULL或 -1， 则 需 要 加 以 说 明 。 比 如 ：Private: /记 录 表 中 实 体 的 总 数 /用 于 确 保 不 打 破 数 量 限 制 。 /-1意 味 着 表 的 实 体 数 未 知 int num_total_entries; 全 局 变 量 (Global Variables)和 数 据 成 员 一 样 ， 所 有 全 局 变 量 应 该 有 一 个 描 述 其 功 能 及 其 意义 的 注 释 。 比 如/ 所 有 本 次 回 归 测 试 使 用 到 的 测 试 用 例 数cosnt int kNumTestCases = 6;实 现 注 释 (Implementation Comments)在 实 现 中 ， 应 该 对 你 代 码 技 巧 性 的 、 不 明 显 的 、 有 趣 的 或 者 重要 的 部 分 进 行 注 释 。类 数 据 成 员 (Class Data Members)技 巧 性 的 和 复 杂 难 懂 的 代 码 块 前 应 该 有 注 释 ：/ Divide result by two, taking into account that x / contains the carry from the addfor(int i = 0;i size();i+) x = (x 1; X 行 注 释 (Line Comments)同 样 ， 当 行 代 码 中 有 不 明 显 的 地 方 时 ， 也 需 要 在 其 行 末 添 加注 释 。 这 种 行 末 注 释 应 该 以 2个 空 白 与 代 码 分 开 。/ If we have enough money, mmap the data portion too.mmap_budget = max(0,mmap_budget index_-length();if(mmap_budget = data_size / Error already logged.可 以 看 到 ， 这 里 即 有 描 述 代 码 功 能 的 注 释 ， 也 有 提 醒 函 数 返 回 时错 误 已 经 被 记 录 的 注 释 。如 果 有 多 行 注 释 ， 将 它 们 整 齐 排 列 将 增 加 可 读 性 。 DoSomething(); / Comment here so the comments line upDoSomethingElseThatIsLong(); / Comment here so there are two spaces / between the code and the comment/ One space before commnet when opening a new scope is allowed, / thus the comment lines up with the following comments and code DoSomethingElse(); / Two spaces before line comments normally 逻 辑 功 能 段 进 行 注 释当 给 函 数 传 入 NULL、 布 尔 值 和 整 型 值 串 时 ， 应 该 增 加 注 释以 说 明 这 些 值 的 意 义 ， 或 者 你 可 以 使 用 常 量 使 代 码 自 文 档 化 。比 较 以 下 两 段 代 码 ：bool success = CalculateSomething(interesting_value, 10, false, NULL);/这 些 参 数 都是 什 么 意 思 ？VS bool success = CalculateSomething(interesting_value, 10, /默 认 基 数 flase,/非 第 一 次 调 用 NULL);/无 回 调 也 可 以 使 用 替 代 方 案 ， 常 量 或 自 描 述 的 变 量 ：const int kDefaultBaseValue = 10;const bool kFirstTimeCalling = false;callback *null_callback = NULL;bool success = CalculateSomething(interesting_value, kDefaultBaseValue, kFirstTimeCalling, null_callback);不 要 这 么 做 ：不 要 试 图 描 述 代 码 本 身 。 假 设 代 码 阅 读 者 比 你 更 了 解 C+， 既 使这 样 ， 他 /她 也 对 你 到 底 想 做 什 么 毫 无 头 绪 。 / 现 在 遍 历b数 组 并 且 确 保 如 果i存 在 ， 下 一 个 元 素 是i+1。./ 天 哪 ， 这 些 都 是 垃 圾 注 释 函 数 声 明 和 定 义 、 函 数 调 用 、 条件 语 句 、 循 环 语 句 和 类 的 格 式 规范 函 数 声 明 与 定 义 (Function Declarations and Definitions)返 回 类 型 和 函 数 名 在 同 一 行 ， 如 果 空 间 足 够 ， 参 数 列 表 也 应 在同 一 行 。 即 ：ReturnType ClassName:FunctionName(Type par_name1,Type par_name2) DoSomething(); .如 果 一 行 输 入 不 完 ， 可 以 分 成 多 行 ： ReturnType ClassName:ReallyLongFunctionName(Type par_name1,Type par_name2, Type par_name3) DoSomething(); . 也 可 以 每 个 参 数 各 占 一 行 ：ReturnType LongClassName:ReallyRealyReallyLongFunctionName(Type par_name1, / 4个 空 格 的 缩 进Type par_nane2,Type par_name3) DoSomething(); 需 要 注 意 的 地 方 ：返 回 类 型 应 该 保 持 与 函 数 名 在 同 一 行 ；左 括 号 应 该 与 函 数 名 保 持 在 同 一 行 且 中 间 不 应 该 有 空 格 ；括 号 与 参 数 之 间 不 应 该 有 空 格 ；左 花 括 号 应 该 与 最 后 一 个 参 数 保 持 在 同 一 行 ；右 花 括 号 要 么 独 自 一 行 ， 要 么 与 左 花 括 号 保 持 在 同 一 行 （ 其 他 风 格规 则 允 许 时 ） ；右 圆 括 号 与 左 花 括 号 之 间 应 该 有 一 个 空 格 隔 开 ；无 论 是 函 数 声 明 还 是 函 数 实 现 ， 都 应 该 给 参 数 命 以 同 样 的 名 称 ；默 认 缩 进 2个 空 格 ；分 行 的 参 数 以 4个 空 格 缩 进 ； 定 义 const函 数 时 ， const关 键 字 应 该 与 最 后 一 个 参 数 保 持 在 同 一 行 。/ 这 个 函 数 签 名 中 的 所 有 代 码 不 超 过80个 字 符ReturnType FunctionName(Type par) const ./ 这 个 函 数 签 名 需 要 分 行 ， 但 注 意 ，const与 最 后 一 个 参 数 保 持 在 同 一 行ReturnType ReallyLongFunctionName(Type par1, Type par2)const . 如 果 有 未 使 用 参 数 ， 在 函 数 实 现 中 注 释 其 名 称 ：/ 在 接 口 中 ， 参 数 一 定 要 命 名class Shape public:virtual void Rotate(double radians) = 0;/ 在 声 明 中 ， 参 数 一 定 要 命 名class Circle : public Shape virtual void Rotate(double radians);/ 在 函 数 实 现 中 ， 以 注 释 注 明 未 使 用 的 参 数 命 名void Circle:Rotate(double /*radians*/)/ 不 好 如 果 以 后 需 要 其 他 人 实 现 ， 参 数 名 称 不 详void Circle:Rotate(double) 函 数 调 用 (Function Calls)尽 量 书 写 在 一 行 ， 如 果 字 符 太 多 ， 将 参 数 分 行 。 比 如 ：bool retval = DoSomething(argument1,argument2,argumetn3);如 果 参 数 无 法 在 同 一 行 内 写 完 ， 可 以 分 行 ， 每 一 行 的 参 数 都 应该 与 第 一 个 参 数 对 齐 ， 且 不 要 在 左 圆 括 号 后 或 右 圆 括 号 前 加 空格 。bool retval = DoSomething(averyveryveryverylongargument1, argument2,argument3);如 果 函 数 参 数 太 多 ， 可 以 每 一 行 写 一 个 参 数 ， 这 样 代 码 更 可 读 ： bool retval = DoSomething(argument1, argument2, argument3, argument4); 如 果 参 数 签 名 太 长 ， 超 过 最 大 行 宽 ， 可 以 将 参 数 分 行 写 书 ：if(.) . . if(.) DoSomethingTheatRequiresALongFunctionName( very_long_argument1, / 缩 进4个 空 格 argument2, argument3, argument4); 条 件 语 句 (Conditonals)括 号 内 最 好 不 要 有 空 格 ， else应 该 另 起 一 行 。基 本 条 件 语 句 主 要 有 两 种 常 见 格 式 ： 一 种 是 在 括 号 和 条 件 中 插 入 空 格 ，另 一 种 是 没 有 。 但 后 者 更 常 用 。 尽 管 两 种 方 式 都 可 以 ， 但 注 意 保 持 一致 性 。 当 你 修 改 别 人 的 代 码 时 ， 保 持 与 已 有 风 格 的 一 致 ； 而 当 你 添 加新 代 码 时 ， 与 当 前 目 录 或 项 目 中 已 有 代 码 的 风 格 保 持 一 致 。 当 你 不 确定 而 且 感 觉 无 所 谓 时 ， 不 要 插 入 空 格 。if(condition) / 括 号 内 没 有 空 格 . / 缩 进2个 空 格else / else与 右 花 括 号 在 同 一 行 . 当 然 ， 你 也 可 以 根 据 自 己 的 喜 好 在 括 号 内 插 入 空 格if ( condition ) / 括 号 内 插 入 空 格 不 常 用 . / 缩 进2个 空 格else / else与 右 花 括 号 在 同 一 行 .注 意 ： if和 左 圆 括 号 之 间 应 该 有 空 格 。 右 圆 括 号 和 左 花 括号 （ 如 果 使 用 ） 之 间 也 应 该 有 空 格 。if(condition) / 糟 糕 IF后 面 没 有 空 格if (condition) / 糟 糕 右 圆 括 号 和 左 花 括 号 之 间 没 有 空 格if(condition) / 非 常 糟 糕 为 便 于 阅 读 ， 简 短 的 条 件 语 句 可 以 写 在 同 一 行 。 但 仅 限 于 这 行 代码 很 明 确 且 没 有 else分 支 的 情 况 ：if (x = kFoo) return new Foo();if (x = kBar) return new Bar();/ if语 句 有else分 支 ， 不 允 许 写 在 同 一 行if (x) DoThis();else DoThat();通 常 ， 单 语 句 条 件 语 句 不 需 要 花 括 号 ， 但 可 以 根 据 自 己 的 喜 好加 上 。 有 复 杂 条 件 和 语 句 的 条 件 和 循 环 加 上 圆 括 号 后 更 具 可 读性 。 一 些 项 目 甚 至 要 求 if在 所 有 情 况 都 应 该 加 上 花 括 号 。if ( condition ) DoSomething(); / 缩 进2个 空 格if (condition) DoSomethign(); 为 保 持 一 致 ， if或 者 else分 支 加 了 花 括 号 ， 另 一 分 支 也 应 该 加 上 。/ 不 允 许 if分 支 有 花 括 号 ， 而else分 支 没 有if (condition) foo;else Bar;/ 不 允 许 else分 支 有 花 括 号 ， 而if分 支 没 有If (condition) foo;else bar;/ if和else分 支 都 应 该 加 上 花 括 号 ， 因 为 它 们 之 一 有if (condition) foo;else Bar; 循 环 和 多 分 支 语 句 (Loops and Switch Statements)在 多 分 支 语 句 中 ， 块 可 以 用 花 括 号 限 制 。 而 对 于 无 循 环 体 的 循 环 ，可 以 使 用 或 continue。 case语 句 块 可 根 据 自 己 的 喜 好 使 用 花 括 号 ，如 果 使 用 花 括 号 ， 请 遵 照 下 面 的 格 式 ：除 非 是 判 断 枚 举 类 型 ， 多 分 支 语 句 应 该 有 一 个 默 认 分 支 （ 在 枚 举 情况 下 ， 编 译 器 将 检 测 到 未 处 理 分 支 并 警 告 ） 。 如 果 默 认 分 支 不 可 能被 执 行 ， 使 用 断 言 (assert)声 明 。swtich (var) case 0: .Break;case 1: . Break;default: assert(false); 空 循 环 体 应 该 用 或 者 continue， 但 不 要 用 单 独 的 分 号 ：while (condition) / 一 直 测 试 条 件 ， 直 到 它 返 回 假for(int i = 0; i kSomeNumber;+i) / 很 好 空 循 环 体while (condtiton) continue; / 很 好 continue指 示 无 逻 辑while (condition); / 糟 糕 看 起 来 像 是do/while循 环 类 格 式 (Class Format)成 员 按 public、 protected和 private的 次 序 定 义 ， 每 个 部 分 缩 进 1个 空格 。 下 例 显 示 了 基 本 的 类 格 式 （ 例 子 中 缺 少 必 要 的 注 释 ， 参 见 类 注释 (Class Comments)部 分 ） ：class MyClass : public OtherClass public: / 注 意 ， 缩 进1个 空 格 MyClass(); / 注 意 ， 缩 进2个 空 格 Explicit MyClass(int var); MyClass() void SomeFunction(); void SomeFunctionThatDoesNothing()void set_some_var(int var) some_var = var; int some_var() const reurn some_var; private: bool SomeInternalFunction(); int some_var; int some_other_var; DISALLOW_COPY_AND_ASSIGN(MyClass); 注 意 ：基 类 名 称 直 接 置 于 子 类 名 称 后 的 同 一 行 内 而 不 受 最 大 长 度 （ 80字 符 ） 的 限 制 ；public:protected:和 private:只 需 缩 进 1个 空 格 ， 且 除 非 是 第 1个实 例 的 情 况 ， 它 们 应 该 位 于 单 独 的 行 ， 最 好 在 紧 接 着 的 下 一 行进 行 成 员 声 明 ；public部 分 行 1位 、 protected部 分 第 2位 ， private放 在 最 后 ； 谢 谢