Java 编 码 规 范 名 称 Java 语 言 编 码 规 范 (Java Code Conventions) 译 者 晨 光 (Morning) 声 明 如 需 复 制 传 播, 请 附 上 本 声 明, 谢 谢 原 文 出 处 : http://java.sun.com/docs/codeconv/html/codeconvtoc.doc.html, 译 文 出 处 :http://morningspace.51.net/,moyingzz@etang.com 说 明 ICA 整 理 版 本
目 录 1 介 绍 (Introduction)...3 1.1 为 什 么 要 有 编 码 规 范 (Why Have Code Conventions)...3 1.2 版 权 声 明 (Acknowledgments)...3 2 文 件 名 (File Names)...3 2.1 文 件 后 缀 (File Suffixes)...3 2.2 常 用 文 件 名 (Common File Names)...3 3 文 件 组 织 (File Organization)...4 3.1 Java 源 文 件 (Java Source Files)...4 4 缩 进 排 版 (Indentation)...5 4.1 行 长 度 (Line Length)...5 4.2 换 行 (Wrapping Lines)...5 5 注 释 (Comments)...7 5.1 实 现 注 释 的 格 式 (Implementation Comment Formats)...8 5.2 文 档 注 释 (Documentation Comments)...10 6 声 明 (Declarations)...11 6.1 每 行 声 明 变 量 的 数 量 (Number Per Line)...11 6.2 初 始 化 (Initialization)...12 6.3 布 局 (Placement)...12 6.4 类 和 接 口 的 声 明 (Class and Interface Declarations)...13 7 语 句 (Statements)...13 7.1 简 单 语 句 (Simple Statements)...13 7.2 复 合 语 句 (Compound Statements)...14 7.3 返 回 语 句 (return Statements)...14 7.4 if,if-else,if else-if else 语 句 (if, if-else, if else-if else Statements)...14 7.5 for 语 句 (for Statements)...15 7.6 while 语 句 (while Statements)...15 7.7 do-while 语 句 (do-while Statements)...16 7.9 try-catch 语 句 (try-catch Statements)...17 8 空 白 (White Space)...17 8.1 空 行 (Blank Lines)...17 8.2 空 格 (Blank Spaces)...18 9 命 名 规 范 (Naming Conventions)...18 10 编 程 惯 例 (Programming Practices)...20 10.1 提 供 对 实 例 以 及 类 变 量 的 访 问 控 制 (Providing Access to Instance and Class Variables)...20 10.2 引 用 类 变 量 和 类 方 法 (Referring to Class Variables and Methods)...20 10.3 常 量 (Constants)...20 10.4 变 量 赋 值 (Variable Assignments)...20 10.5 其 它 惯 例 (Miscellaneous Practices)...21 11 代 码 范 例 (Code Examples)...23 11.1 Java 源 文 件 范 例 (Java Source File Example)...23 2
1 介 绍 (Introduction) 1.1 为 什 么 要 有 编 码 规 范 (Why Have Code Conventions) 编 码 规 范 对 于 程 序 员 而 言 尤 为 重 要, 有 以 下 几 个 原 因 : - 一 个 软 件 的 生 命 周 期 中,80% 的 花 费 在 于 维 护 - 几 乎 没 有 任 何 一 个 软 件, 在 其 整 个 生 命 周 期 中, 均 由 最 初 的 开 发 人 员 来 维 护 - 编 码 规 范 可 以 改 善 软 件 的 可 读 性, 可 以 让 程 序 员 尽 快 而 彻 底 地 理 解 新 的 代 码 - 如 果 你 将 源 码 作 为 产 品 发 布, 就 需 要 确 任 它 是 否 被 很 好 的 打 包 并 且 清 晰 无 误, 一 如 你 已 构 建 的 其 它 任 何 产 品 为 了 执 行 规 范, 每 个 软 件 开 发 人 员 必 须 一 致 遵 守 编 码 规 范 每 个 人 1.2 版 权 声 明 (Acknowledgments) 本 文 档 反 映 的 是 Sun MicroSystems 公 司,Java 语 言 规 范 中 的 编 码 标 准 部 分 主 要 贡 献 者 包 括 :Peter King,Patrick Naughton,Mike DeMoney,Jonni Kanerva,Kathy Walrath 以 及 Scott Hommel 本 文 档 现 由 Scott Hommel 维 护, 有 关 评 论 意 见 请 发 至 shommel@eng.sun.com 2 文 件 名 (File Names) 这 部 分 列 出 了 常 用 的 文 件 名 及 其 后 缀 2.1 文 件 后 缀 (File Suffixes) Java 程 序 使 用 下 列 文 件 后 缀 : 文 件 类 别 Java 源 文 件 文 件 后 缀.java Java 字 节 码 文 件.class 2.2 常 用 文 件 名 (Common File Names) 常 用 的 文 件 名 包 括 : 3
文 件 名 用 途 GNUmakefile makefiles 的 首 选 文 件 名 我 们 采 用 gnumake 来 创 建 (build) 软 件 README 概 述 特 定 目 录 下 所 含 内 容 的 文 件 的 首 选 文 件 名 3 文 件 组 织 (File Organization) 一 个 文 件 由 被 空 行 分 割 而 成 的 段 落 以 及 标 识 每 个 段 落 的 可 选 注 释 共 同 组 成 超 过 2000 行 的 程 序 难 以 阅 读, 应 该 尽 量 避 免 "Java 源 文 件 范 例 " 提 供 了 一 个 布 局 合 理 的 Java 程 序 范 例 3.1 Java 源 文 件 (Java Source Files) 每 个 Java 源 文 件 都 包 含 一 个 单 一 的 公 共 类 或 接 口 若 私 有 类 和 接 口 与 一 个 公 共 类 相 关 联, 可 以 将 它 们 和 公 共 类 放 入 同 一 个 源 文 件 公 共 类 必 须 是 这 个 文 件 中 的 第 一 个 类 或 接 口 Java 源 文 件 还 遵 循 以 下 规 则 : - 开 头 注 释 ( 参 见 " 开 头 注 释 ") - 包 和 引 入 语 句 ( 参 见 " 包 和 引 入 语 句 ") - 类 和 接 口 声 明 ( 参 见 " 类 和 接 口 声 明 ") 3.1.1 开 头 注 释 (Beginning Comments) 所 有 的 源 文 件 都 应 该 在 开 头 有 一 个 C 语 言 风 格 的 注 释, 其 中 列 出 类 名 版 本 信 息 日 期 和 版 权 声 明 : /* * Classname * * Version information * * Date * * Copyright notice */ 3.1.2 包 和 引 入 语 句 (Package and Import Statements) 在 多 数 Java 源 文 件 中, 第 一 个 非 注 释 行 是 包 语 句 在 它 之 后 可 以 跟 引 入 语 句 例 如 : 4
package java.awt; import java.awt.peer.canvaspeer; 3.1.3 类 和 接 口 声 明 (Class and Interface Declarations) 下 表 描 述 了 类 和 接 口 声 明 的 各 个 部 分 以 及 它 们 出 现 的 先 后 次 序 参 见 "Java 源 文 件 范 例 " 中 一 个 包 含 注 释 的 例 子 类 / 接 口 声 明 的 各 部 分 类 / 接 口 文 档 注 释 (/** */) 类 或 接 口 的 声 明 类 / 接 口 实 现 的 注 释 (/* */) 如 果 有 必 要 的 话 类 的 ( 静 态 ) 变 量 实 例 变 量 构 造 器 方 法 注 解 该 注 释 中 所 需 包 含 的 信 息, 参 见 " 文 档 注 释 " 该 注 释 应 包 含 任 何 有 关 整 个 类 或 接 口 的 信 息, 而 这 些 信 息 又 不 适 合 作 为 类 / 接 口 文 档 注 释 首 先 是 类 的 公 共 变 量, 随 后 是 保 护 变 量, 再 后 是 包 一 级 别 的 变 量 ( 没 有 访 问 修 饰 符,access modifier), 最 后 是 私 有 变 量 首 先 是 公 共 级 别 的, 随 后 是 保 护 级 别 的, 再 后 是 包 一 级 别 的 ( 没 有 访 问 修 饰 符 ), 最 后 是 私 有 级 别 的 这 些 方 法 应 该 按 功 能, 而 非 作 用 域 或 访 问 权 限, 分 组 例 如, 一 个 私 有 的 类 方 法 可 以 置 于 两 个 公 有 的 实 例 方 法 之 间 其 目 的 是 为 了 更 便 于 阅 读 和 理 解 代 码 4 缩 进 排 版 (Indentation) 4 个 空 格 常 被 作 为 缩 进 排 版 的 一 个 单 位 缩 进 的 确 切 解 释 并 未 详 细 指 定 ( 空 格 vs. 制 表 符 ) 一 个 制 表 符 等 于 8 个 空 格 ( 而 非 4 个 ) 4.1 行 长 度 (Line Length) 尽 量 避 免 一 行 的 长 度 超 过 80 个 字 符, 因 为 很 多 终 端 和 工 具 不 能 很 好 处 理 之 注 意 : 用 于 文 档 中 的 例 子 应 该 使 用 更 短 的 行 长, 长 度 一 般 不 超 过 70 个 字 符 4.2 换 行 (Wrapping Lines) 当 一 个 表 达 式 无 法 容 纳 在 一 行 内 时, 可 以 依 据 如 下 一 般 规 则 断 开 之 : 5
- 在 一 个 逗 号 后 面 断 开 - 在 一 个 操 作 符 前 面 断 开 - 宁 可 选 择 较 高 级 别 (higher-level) 的 断 开, 而 非 较 低 级 别 (lower-level) 的 断 开 - 新 的 一 行 应 该 与 上 一 行 同 一 级 别 表 达 式 的 开 头 处 对 齐 - 如 果 以 上 规 则 导 致 你 的 代 码 混 乱 或 者 使 你 的 代 码 都 堆 挤 在 右 边, 那 就 代 之 以 缩 进 8 个 空 格 以 下 是 断 开 方 法 调 用 的 一 些 例 子 : somemethod(longexpression1, longexpression2, longexpression3, longexpression4, longexpression5); var = somemethod1(longexpression1, somemethod2(longexpression2, longexpression3)); 以 下 是 两 个 断 开 算 术 表 达 式 的 例 子 前 者 更 好, 因 为 断 开 处 位 于 括 号 表 达 式 的 外 边, 这 是 个 较 高 级 别 的 断 开 longname1 = longname2 * (longname3 + longname4 - longname5) + 4 * longname6; //PREFFER longname1 = longname2 * (longname3 + longname4 - longname5) + 4 * longname6; //AVOID 以 下 是 两 个 缩 进 方 法 声 明 的 例 子 前 者 是 常 规 情 形 后 者 若 使 用 常 规 的 缩 进 方 式 将 会 使 第 二 行 和 第 三 行 移 得 很 靠 右, 所 以 代 之 以 缩 进 8 个 空 格 //CONVENTIONAL INDENTATION somemethod(int anarg, Object anotherarg, String yetanotherarg, Object andstillanother) {... //INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronized horkinglongmethodname(int anarg, Object anotherarg, String yetanotherarg, 6
... Object andstillanother) { if 语 句 的 换 行 通 常 使 用 8 个 空 格 的 规 则, 因 为 常 规 缩 进 (4 个 空 格 ) 会 使 语 句 体 看 起 来 比 较 费 劲 比 如 : //DON T USE THIS INDENTATION if ((condition1 && condition2) (condition3 && condition4)!(condition5 && condition6)) { //BAD WRAPS dosomethingaboutit(); //MAKE THIS LINE EASY TO MISS //USE THIS INDENTATION INSTEAD if ((condition1 && condition2) (condition3 && condition4)!(condition5 && condition6)) { dosomethingaboutit(); //OR USE THIS if ((condition1 && condition2) (condition3 && condition4)!(condition5 && condition6)) { dosomethingaboutit(); 这 里 有 三 种 可 行 的 方 法 用 于 处 理 三 元 运 算 表 达 式 : alpha = (alongbooleanexpression)? beta : gamma; alpha = (alongbooleanexpression)? beta : gamma; alpha = (alongbooleanexpression)? beta : gamma; 5 注 释 (Comments) 7
Java 程 序 有 两 类 注 释 : 实 现 注 释 (implementation comments) 和 文 档 注 释 (document comments) 实 现 注 释 是 那 些 在 C++ 中 见 过 的, 使 用 /*...*/ 和 // 界 定 的 注 释 文 档 注 释 ( 被 称 为 "doc comments") 是 Java 独 有 的, 并 由 /**...*/ 界 定 文 档 注 释 可 以 通 过 javadoc 工 具 转 换 成 HTML 文 件 实 现 注 释 用 以 注 释 代 码 或 者 实 现 细 节 文 档 注 释 从 实 现 自 由 (implementation-free) 的 角 度 描 述 代 码 的 规 范 它 可 以 被 那 些 手 头 没 有 源 码 的 开 发 人 员 读 懂 注 释 应 被 用 来 给 出 代 码 的 总 括, 并 提 供 代 码 自 身 没 有 提 供 的 附 加 信 息 注 释 应 该 仅 包 含 与 阅 读 和 理 解 程 序 有 关 的 信 息 例 如, 相 应 的 包 如 何 被 建 立 或 位 于 哪 个 目 录 下 之 类 的 信 息 不 应 包 括 在 注 释 中 在 注 释 里, 对 设 计 决 策 中 重 要 的 或 者 不 是 显 而 易 见 的 地 方 进 行 说 明 是 可 以 的, 但 应 避 免 提 供 代 码 中 己 清 晰 表 达 出 来 的 重 复 信 息 多 余 的 的 注 释 很 容 易 过 时 通 常 应 避 免 那 些 代 码 更 新 就 可 能 过 时 的 注 释 注 意 : 频 繁 的 注 释 有 时 反 映 出 代 码 的 低 质 量 当 你 觉 得 被 迫 要 加 注 释 的 时 候, 考 虑 一 下 重 写 代 码 使 其 更 清 晰 注 释 不 应 写 在 用 星 号 或 其 他 字 符 画 出 来 的 大 框 里 注 释 不 应 包 括 诸 如 制 表 符 和 回 退 符 之 类 的 特 殊 字 符 5.1 实 现 注 释 的 格 式 (Implementation Comment Formats) 程 序 可 以 有 4 种 实 现 注 释 的 风 格 : 块 (block) 单 行 (single-line) 尾 端 (trailing) 和 行 末 (end-of-line) 5.1.1 块 注 释 (Block Comments) 块 注 释 通 常 用 于 提 供 对 文 件, 方 法, 数 据 结 构 和 算 法 的 描 述 块 注 释 被 置 于 每 个 文 件 的 开 始 处 以 及 每 个 方 法 之 前 它 们 也 可 以 被 用 于 其 他 地 方, 比 如 方 法 内 部 在 功 能 和 方 法 内 部 的 块 注 释 应 该 和 它 们 所 描 述 的 代 码 具 有 一 样 的 缩 进 格 式 块 注 释 之 首 应 该 有 一 个 空 行, 用 于 把 块 注 释 和 代 码 分 割 开 来, 比 如 : /* * Here is a block comment. */ 块 注 释 可 以 以 /*- 开 头, 这 样 indent(1) 就 可 以 将 之 识 别 为 一 个 代 码 块 的 开 始, 而 不 会 重 8
排 它 /*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */ 注 意 : 如 果 你 不 使 用 indent(1), 就 不 必 在 代 码 中 使 用 /*-, 或 为 他 人 可 能 对 你 的 代 码 运 行 indent(1) 作 让 步 参 见 " 文 档 注 释 " 5.1.2 单 行 注 释 (Single-Line Comments) 短 注 释 可 以 显 示 在 一 行 内, 并 与 其 后 的 代 码 具 有 一 样 的 缩 进 层 级 如 果 一 个 注 释 不 能 在 一 行 内 写 完, 就 该 采 用 块 注 释 ( 参 见 " 块 注 释 ") 单 行 注 释 之 前 应 该 有 一 个 空 行 以 下 是 一 个 Java 代 码 中 单 行 注 释 的 例 子 : if (condition) { /* Handle the condition. */... 5.1.3 尾 端 注 释 (Trailing Comments) 极 短 的 注 释 可 以 与 它 们 所 要 描 述 的 代 码 位 于 同 一 行, 但 是 应 该 有 足 够 的 空 白 来 分 开 代 码 和 注 释 若 有 多 个 短 注 释 出 现 于 大 段 代 码 中, 它 们 应 该 具 有 相 同 的 缩 进 以 下 是 一 个 Java 代 码 中 尾 端 注 释 的 例 子 : if (a == 2) { return TRUE; /* special case */ else { return isprime(a); /* works only for odd a */ 9
5.1.4 行 末 注 释 (End-Of-Line Comments) 注 释 界 定 符 "//", 可 以 注 释 掉 整 行 或 者 一 行 中 的 一 部 分 它 一 般 不 用 于 连 续 多 行 的 注 释 文 本 ; 然 而, 它 可 以 用 来 注 释 掉 连 续 多 行 的 代 码 段 以 下 是 所 有 三 种 风 格 的 例 子 : if (foo > 1) { // Do a double-flip.... else { return false; // Explain why here. //if (bar > 1) { // // // Do a triple-flip. //... // //else { // return false; // 5.2 文 档 注 释 (Documentation Comments) 注 意 : 此 处 描 述 的 注 释 格 式 之 范 例, 参 见 "Java 源 文 件 范 例 " 若 想 了 解 更 多, 参 见 "How to Write Doc Comments for Javadoc", 其 中 包 含 了 有 关 文 档 注 释 标 记 的 信 息 (@return, @param, @see): http://java.sun.com/javadoc/writingdoccomments/index.html 若 想 了 解 更 多 有 关 文 档 注 释 和 javadoc 的 详 细 资 料, 参 见 javadoc 的 主 页 : http://java.sun.com/javadoc/index.html 文 档 注 释 描 述 Java 的 类 接 口 构 造 器, 方 法, 以 及 字 段 (field) 每 个 文 档 注 释 都 会 被 置 于 注 释 定 界 符 /**...*/ 之 中, 一 个 注 释 对 应 一 个 类 接 口 或 成 员 该 注 释 应 位 于 声 明 10
之 前 : /** * The Example class provides... */ public class Example {... 注 意 顶 层 (top-level) 的 类 和 接 口 是 不 缩 进 的, 而 其 成 员 是 缩 进 的 描 述 类 和 接 口 的 文 档 注 释 的 第 一 行 (/**) 不 需 缩 进 ; 随 后 的 文 档 注 释 每 行 都 缩 进 1 格 ( 使 星 号 纵 向 对 齐 ) 成 员, 包 括 构 造 函 数 在 内, 其 文 档 注 释 的 第 一 行 缩 进 4 格, 随 后 每 行 都 缩 进 5 格 若 你 想 给 出 有 关 类 接 口 变 量 或 方 法 的 信 息, 而 这 些 信 息 又 不 适 合 写 在 文 档 中, 则 可 使 用 实 现 块 注 释 ( 见 5.1.1) 或 紧 跟 在 声 明 后 面 的 单 行 注 释 ( 见 5.1.2) 例 如, 有 关 一 个 类 实 现 的 细 节, 应 放 入 紧 跟 在 类 声 明 后 面 的 实 现 块 注 释 中, 而 不 是 放 在 文 档 注 释 中 文 档 注 释 不 能 放 在 一 个 方 法 或 构 造 器 的 定 义 块 中, 因 为 Java 会 将 位 于 文 档 注 释 之 后 的 第 一 个 声 明 与 其 相 关 联 6 声 明 (Declarations) 6.1 每 行 声 明 变 量 的 数 量 (Number Per Line) 推 荐 一 行 一 个 声 明, 因 为 这 样 以 利 于 写 注 释 亦 即, int level; // indentation level int size; // size of table 要 优 于, int level, size; 不 要 将 不 同 类 型 变 量 的 声 明 放 在 同 一 行, 例 如 : int foo, fooarray[]; //WRONG! 注 意 : 上 面 的 例 子 中, 在 类 型 和 标 识 符 之 间 放 了 一 个 空 格, 另 一 种 被 允 许 的 替 代 方 式 是 使 用 11
制 表 符 : int level; // indentation level int size; // size of table Object currententry; // currently selected table entry 6.2 初 始 化 (Initialization) 尽 量 在 声 明 局 部 变 量 的 同 时 初 始 化 唯 一 不 这 么 做 的 理 由 是 变 量 的 初 始 值 依 赖 于 某 些 先 前 发 生 的 计 算 6.3 布 局 (Placement) 只 在 代 码 块 的 开 始 处 声 明 变 量 ( 一 个 块 是 指 任 何 被 包 含 在 大 括 号 "{" 和 "" 中 间 的 代 码 ) 不 要 在 首 次 用 到 该 变 量 时 才 声 明 之 这 会 把 注 意 力 不 集 中 的 程 序 员 搞 糊 涂, 同 时 会 妨 碍 代 码 在 该 作 用 域 内 的 可 移 植 性 void mymethod() { int int1 = 0; // beginning of method block if (condition) { int int2 = 0;... // beginning of "if" block 该 规 则 的 一 个 例 外 是 for 循 环 的 索 引 变 量 for (int i = 0; i < maxloops; i++) {... 避 免 声 明 的 局 部 变 量 覆 盖 上 一 级 声 明 的 变 量 例 如, 不 要 在 内 部 代 码 块 中 声 明 相 同 的 变 量 名 : int count;... mymethod() { 12
if (condition) { int count = 0;...... // AVOID! 6.4 类 和 接 口 的 声 明 (Class and Interface Declarations) 当 编 写 类 和 接 口 是, 应 该 遵 守 以 下 格 式 规 则 : - 在 方 法 名 与 其 参 数 列 表 之 前 的 左 括 号 "(" 间 不 要 有 空 格 - 左 大 括 号 "{" 位 于 声 明 语 句 同 行 的 末 尾 - 右 大 括 号 "" 另 起 一 行, 与 相 应 的 声 明 语 句 对 齐, 除 非 是 一 个 空 语 句,"" 应 紧 跟 在 "{" 之 后 class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; int emptymethod() {... - 方 法 与 方 法 之 间 以 空 行 分 隔 7 语 句 (Statements) 7.1 简 单 语 句 (Simple Statements) 每 行 至 多 包 含 一 条 语 句, 例 如 : argv++; // Correct 13
argc--; // Correct argv++; argc--; // AVOID! 7.2 复 合 语 句 (Compound Statements) 复 合 语 句 是 包 含 在 大 括 号 中 的 语 句 序 列, 形 如 "{ 语 句 " 例 如 下 面 各 段 - 被 括 其 中 的 语 句 应 该 较 之 复 合 语 句 缩 进 一 个 层 次 - 左 大 括 号 "{" 应 位 于 复 合 语 句 起 始 行 的 行 尾 ; 右 大 括 号 "" 应 另 起 一 行 并 与 复 合 语 句 首 行 对 齐 - 大 括 号 可 以 被 用 于 所 有 语 句, 包 括 单 个 语 句, 只 要 这 些 语 句 是 诸 如 if-else 或 for 控 制 结 构 的 一 部 分 这 样 便 于 添 加 语 句 而 无 需 担 心 由 于 忘 了 加 括 号 而 引 入 bug 7.3 返 回 语 句 (return Statements) 一 个 带 返 回 值 的 return 语 句 不 使 用 小 括 号 "()", 除 非 它 们 以 某 种 方 式 使 返 回 值 更 为 显 见 例 如 : return; return mydisk.size(); return (size? size : defaultsize); 7.4 if,if-else,if else-if else 语 句 (if, if-else, if else-if else Statements) if-else 语 句 应 该 具 有 如 下 格 式 : if (condition) { if (condition) { else { 14
if (condition) { else if (condition) { else{ 注 意 :if 语 句 总 是 用 "{" 和 "" 括 起 来, 避 免 使 用 如 下 容 易 引 起 错 误 的 格 式 : if (condition) //AVOID! THIS OMITS THE BRACES {! statement; 7.5 for 语 句 (for Statements) 一 个 for 语 句 应 该 具 有 如 下 格 式 : for (initialization; condition; update) { 一 个 空 的 for 语 句 ( 所 有 工 作 都 在 初 始 化, 条 件 判 断, 更 新 子 句 中 完 成 ) 应 该 具 有 如 下 格 式 : for (initialization; condition; update); 当 在 for 语 句 的 初 始 化 或 更 新 子 句 中 使 用 逗 号 时, 避 免 因 使 用 三 个 以 上 变 量, 而 导 致 复 杂 度 提 高 若 需 要, 可 以 在 for 循 环 之 前 ( 为 初 始 化 子 句 ) 或 for 循 环 末 尾 ( 为 更 新 子 句 ) 使 用 单 独 的 语 句 7.6 while 语 句 (while Statements) 一 个 while 语 句 应 该 具 有 如 下 格 式 15
while (condition) { 一 个 空 的 while 语 句 应 该 具 有 如 下 格 式 : while (condition); 7.7 do-while 语 句 (do-while Statements) 一 个 do-while 语 句 应 该 具 有 如 下 格 式 : do { while (condition); 7.8 switch 语 句 (switch Statements) 一 个 switch 语 句 应 该 具 有 如 下 格 式 : switch (condition) { case ABC: /* falls through */ case DEF: break; case XYZ: break; default: break; 16
每 当 一 个 case 顺 着 往 下 执 行 时 ( 因 为 没 有 break 语 句 ), 通 常 应 在 break 语 句 的 位 置 添 加 注 释 上 面 的 示 例 代 码 中 就 包 含 注 释 /* falls through */ 7.9 try-catch 语 句 (try-catch Statements) 一 个 try-catch 语 句 应 该 具 有 如 下 格 式 : try { catch (ExceptionClass e) { 一 个 try-catch 语 句 后 面 也 可 能 跟 着 一 个 finally 语 句, 不 论 try 代 码 块 是 否 顺 利 执 行 完, 它 都 会 被 执 行 try { catch (ExceptionClass e) { finally { 8 空 白 (White Space) 8.1 空 行 (Blank Lines) 空 行 将 逻 辑 相 关 的 代 码 段 分 隔 开, 以 提 高 可 读 性 下 列 情 况 应 该 总 是 使 用 两 个 空 行 : - 一 个 源 文 件 的 两 个 片 段 (section) 之 间 - 类 声 明 和 接 口 声 明 之 间 17
下 列 情 况 应 该 总 是 使 用 一 个 空 行 : - 两 个 方 法 之 间 - 方 法 内 的 局 部 变 量 和 方 法 的 第 一 条 语 句 之 间 - 块 注 释 ( 参 见 "5.1.1") 或 单 行 注 释 ( 参 见 "5.1.2") 之 前 - 一 个 方 法 内 的 两 个 逻 辑 段 之 间, 用 以 提 高 可 读 性 8.2 空 格 (Blank Spaces) 下 列 情 况 应 该 使 用 空 格 : - 一 个 紧 跟 着 括 号 的 关 键 字 应 该 被 空 格 分 开, 例 如 : while (true) {... 注 意 : 空 格 不 应 该 置 于 方 法 名 与 其 左 括 号 之 间 这 将 有 助 于 区 分 关 键 字 和 方 法 调 用 - 空 白 应 该 位 于 参 数 列 表 中 逗 号 的 后 面 - 所 有 的 二 元 运 算 符, 除 了 ".", 应 该 使 用 空 格 将 之 与 操 作 数 分 开 一 元 操 作 符 和 操 作 数 之 间 不 因 该 加 空 格, 比 如 : 负 号 ("-") 自 增 ("++") 和 自 减 ("--") 例 如 : a += c + d; a = (a + b) / (c * d); while (d++ = s++) { n++; printsize("size is " + foo + "\n"); - for 语 句 中 的 表 达 式 应 该 被 空 格 分 开, 例 如 : for (expr1; expr2; expr3) - 强 制 转 型 后 应 该 跟 一 个 空 格, 例 如 : mymethod((byte) anum, (Object) x); mymethod((int) (cp + 5), ((int) (i + 3)) + 1); 9 命 名 规 范 (Naming Conventions) 命 名 规 范 使 程 序 更 易 读, 从 而 更 易 于 理 解 它 们 也 可 以 提 供 一 些 有 关 标 识 符 功 能 的 信 息, 以 助 于 理 解 代 码, 例 如, 不 论 它 是 一 个 常 量, 包, 还 是 类 18
标 识 符 类 型 命 名 规 则 例 子 包 (Packages) 一 个 唯 一 包 名 的 前 缀 总 是 全 部 小 写 的 ASCII 字 母 并 且 是 一 个 顶 级 域 名, 通 常 是 com,edu,gov,mil,net, com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese org, 或 1981 年 ISO 3166 标 准 所 指 定 的 标 识 国 家 的 英 文 双 字 符 代 码 包 名 的 后 续 部 分 根 据 不 同 机 构 各 自 内 部 的 命 名 规 范 而 不 尽 相 同 这 类 命 名 规 范 可 能 以 特 定 目 录 名 的 组 成 来 区 分 部 门 (department), 项 目 (project), 机 器 (machine), 或 注 册 名 (login names) 类 (Classes) 命 名 规 则 : 类 名 是 个 一 名 词, 采 用 大 小 写 混 合 的 方 式, 每 个 单 词 的 首 字 母 class Raster; class ImageSprite; 大 写 尽 量 使 你 的 类 名 简 洁 而 富 于 描 述 使 用 完 整 单 词, 避 免 缩 写 词 ( 除 非 该 缩 写 词 被 更 广 泛 使 用, 像 URL, HTML) 接 口 命 名 规 则 : 大 小 写 规 则 与 类 名 相 似 interface Storing; (Interfaces) interface RasterDelegate; 方 (Methods) 法 方 法 名 是 一 个 动 词, 采 用 大 小 写 混 合 的 方 式, 第 一 个 单 词 的 首 字 母 小 写, 其 后 单 词 的 首 字 母 大 写 run(); runfast(); getbackground(); 变 量 (Variables) 实 例 变 量 (Instance Variables) 常 量 (Constants) 除 了 变 量 名 外, 所 有 实 例, 包 括 类, 类 常 量, 均 采 用 大 小 写 混 合 的 方 式, 第 一 个 单 词 的 首 字 母 小 写, 其 后 单 词 的 首 字 母 大 写 变 量 名 不 应 以 下 划 线 或 美 元 符 号 开 头, 尽 管 这 在 语 法 上 是 允 许 的 变 量 名 应 简 短 且 富 于 描 述 变 量 名 的 选 用 应 该 易 于 记 忆, 即, 能 够 指 出 其 用 途 尽 量 避 免 单 个 字 符 的 变 量 名, 除 非 是 一 次 性 的 临 时 变 量 临 时 变 量 通 常 被 取 名 为 i,j,k,m 和 n, 它 们 一 般 用 于 整 型 ;c,d,e, 它 们 一 般 用 于 字 符 型 大 小 写 规 则 和 变 量 名 相 似, 除 了 前 面 需 要 一 个 下 划 线 类 常 量 和 ANSI 常 量 的 声 明, 应 该 全 部 大 写, 单 词 间 用 下 划 线 隔 开 ( 尽 量 避 免 ANSI 常 量, 容 易 引 起 错 误 ) char c; int i; float mywidth; int _employeeid; String _name; Customer _customer; static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; 19
static final int GET_THE_CPU = 1; 10 编 程 惯 例 (Programming Practices) 10.1 提 供 对 实 例 以 及 类 变 量 的 访 问 控 制 (Providing Access to Instance and Class Variables) 若 没 有 足 够 理 由, 不 要 把 实 例 或 类 变 量 声 明 为 公 有 通 常, 实 例 变 量 无 需 显 式 的 设 置 (set) 和 获 取 (gotten), 通 常 这 作 为 方 法 调 用 的 边 缘 效 应 (side effect) 而 产 生 一 个 具 有 公 有 实 例 变 量 的 恰 当 例 子, 是 类 仅 作 为 数 据 结 构, 没 有 行 为 亦 即, 若 你 要 使 用 一 个 结 构 (struct) 而 非 一 个 类 ( 如 果 java 支 持 结 构 的 话 ), 那 么 把 类 的 实 例 变 量 声 明 为 公 有 是 合 适 的 10.2 引 用 类 变 量 和 类 方 法 (Referring to Class Variables and Methods) 避 免 用 一 个 对 象 访 问 一 个 类 的 静 态 变 量 和 方 法 应 该 用 类 名 替 代 例 如 : classmethod(); AClass.classMethod(); anobject.classmethod(); //OK //OK //AVOID! 10.3 常 量 (Constants) 位 于 for 循 环 中 作 为 计 数 器 值 的 数 字 常 量, 除 了 -1,0 和 1 之 外, 不 应 被 直 接 写 入 代 码 10.4 变 量 赋 值 (Variable Assignments) 避 免 在 一 个 语 句 中 给 多 个 变 量 赋 相 同 的 值 它 很 难 读 懂 例 如 : foobar.fchar = barfoo.lchar = 'c'; // AVOID! 20
不 要 将 赋 值 运 算 符 用 在 容 易 与 相 等 关 系 运 算 符 混 淆 的 地 方 例 如 : if (c++ = d++) {... // AVOID! (Java disallows) 应 该 写 成 if ((c++ = d++)!= 0) {... 不 要 使 用 内 嵌 (embedded) 赋 值 运 算 符 试 图 提 高 运 行 时 的 效 率, 这 是 编 译 器 的 工 作 例 如 : d = (a = b + c) + r; // AVOID! 应 该 写 成 a = b + c; d = a + r; 10.5 其 它 惯 例 (Miscellaneous Practices) 10.5.1 圆 括 号 (Parentheses) 一 般 而 言, 在 含 有 多 种 运 算 符 的 表 达 式 中 使 用 圆 括 号 来 避 免 运 算 符 优 先 级 问 题, 是 个 好 方 法 即 使 运 算 符 的 优 先 级 对 你 而 言 可 能 很 清 楚, 但 对 其 他 人 未 必 如 此 你 不 能 假 设 别 的 程 序 员 和 你 一 样 清 楚 运 算 符 的 优 先 级 if (a == b && c == d) // AVOID! if ((a == b) && (c == d)) // RIGHT 21
10.5.2 返 回 值 (Returning Values) 设 法 让 你 的 程 序 结 构 符 合 目 的 例 如 : if (booleanexpression) { return true; else { return false; 应 该 代 之 以 如 下 方 法 : return booleanexpression; 类 似 地 : if (condition) { return x; return y; 应 该 写 做 : return (condition? x : y); 10.5.3 条 件 运 算 符 "?" 前 的 表 达 式 (Expressions before '?' in the Conditional Operator) 如 果 一 个 包 含 二 元 运 算 符 的 表 达 式 出 现 在 三 元 运 算 符 "? : " 的 "?" 之 前, 那 么 应 该 给 表 达 式 添 上 一 对 圆 括 号 例 如 : (x >= 0)? x : -x; 10.5.4 特 殊 注 释 (Special Comments) 22
在 注 释 中 使 用 XXX 来 标 识 某 些 未 实 现 (bogus) 的 但 可 以 工 作 (works) 的 内 容 用 FIXME 来 标 识 某 些 假 的 和 错 误 的 内 容 11 代 码 范 例 (Code Examples) 11.1 Java 源 文 件 范 例 (Java Source File Example) 下 面 的 例 子, 展 示 了 如 何 合 理 布 局 一 个 包 含 单 一 公 共 类 的 Java 源 程 序 接 口 的 布 局 与 其 相 似 更 多 信 息 参 见 " 类 和 接 口 声 明 " 以 及 " 文 挡 注 释 " /* * @(#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. * All rights reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. ("Confidential Information"). You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. */ package java.blah; import java.blah.blahdy.blahblah; /** * Class description goes here. * * @version 1.82 18 Mar 1999 * @author Firstname Lastname */ public class Blah extends SomeClass { /* A class implementation comment can go here. */ /** classvar1 documentation comment */ 23
public static int classvar1; /** * classvar2 documentation comment that happens to be * more than one line long */ private static Object classvar2; /** instancevar1 documentation comment */ public Object instancevar1; /** instancevar2 documentation comment */ protected int instancevar2; /** instancevar3 documentation comment */ private Object[] instancevar3; /** *...constructor Blah documentation comment... */ public Blah() { //...implementation goes here... /** *...method dosomething documentation comment... */ public void dosomething() { //...implementation goes here... /** *...method dosomethingelse documentation comment... * @param someparam description */ public void dosomethingelse(object someparam) { //...implementation goes here... 24