JAVA编码规范

JAVA 编 码 规 范 为 什 么 要 有 编 码 规 范? 编 码 规 范 对 于 程 序 员 而 言 尤 为 重 要, 有 以 下 几 个 原 因 : - 一 个 软 件 的 生 命 周 期 中,80% 的 花 费 在 于 维 护 - 几 乎 没 有 任 何 一 个 软 件, 在 其 整 个 生 命 周 期 中, 均 由 最 初 的 开 发 人 员 来 维 护 - 编 码 规 范 可 以 改 善 软 件 的 可 读 性, 可 以 让 程 序 员 尽 快 而 彻 底 地 理 解 新 的 代 码 - 如 果 你 将 源 码 作 为 产 品 发 布, 就 需 要 确 任 它 是 否 被 很 好 的 打 包 并 且 清 晰 无 误 代 码 规 范 是 高 代 码 质 量 和 高 开 发 效 率 的 前 提 代 码 规 范 是 团 队 成 员 之 间 无 阻 碍 交 流 的 保 证 代 码 规 范 能 够 减 少 后 期 维 护 成 本 为 了 执 行 规 范, 每 个 软 件 开 发 人 员 必 须 一 致 遵 守 编 码 规 范 1. 命 名 规 范 定 义 这 个 规 范 的 目 的 是 让 项 目 中 所 有 的 文 档 都 看 起 来 像 一 个 人 写 的, 增 加 1

可 读 性, 减 少 项 目 组 中 因 为 换 人 而 带 来 的 损 失 1.1 包 的 命 名 包 名 命 名 必 须 全 部 是 英 文 的 小 写 字 母, 由 名 词 或 名 词 缩 写 组 成 按 照 国 际 规 例, 包 的 命 名 由 组 织 性 质, 组 织 名 称 缩 写 或 全 名, 系 统 名 称 组 成 比 如 公 司 一 般 用 com, 社 团 用 net, 非 盈 利 的 组 织 用 org 包 末 端 的 名 称 一 般 是 根 据 包 含 的 类 或 接 口 的 职 责, 功 能 来 名 称, 比 如 业 务 逻 辑 的, 可 以 是 service 或 manager, 具 体 实 现 可 能 是 service.impl 包 命 名 的 基 本 原 则 是 能 够 抽 象 出 包 管 辖 的 类 的 职 责 和 功 能 简 单 的 说 就 是 一 看 包 就 知 道 下 面 的 类 是 做 什 么 的 一 些 常 见 的 包 的 命 名 : org.apache.commons.logging.log org.springframework.dao org.hibernate 1.2 类 和 接 口 的 命 名 类 和 接 口 的 名 称 必 须 以 大 写 的 英 文 字 母 开 头, 必 须 是 名 词 或 名 词 短 语, 多 个 名 词 存 在 的 时 候 名 词 的 第 一 字 母 大 写 禁 止 在 名 称 中 出 现 形 容 词 动 词 和 动 词 衍 生 形 式, 比 如 DeleteUser,UpdateDClass,GetNode,MyNode,YourTree 来 命 名 类 和 接 口 名 称 要 有 实 际 的 意 义, 根 据 名 称 就 大 概 知 道 这 个 类 的 职 责 是 什 么 严 禁 使 2

用 Page1,Page2 来 命 名 对 于 Domain model, 直 接 就 是 对 象 的 名 称, 比 如 Book,Address 之 类, 如 果 是 业 务 接 口, 那 就 是 BookManager 或 者 BookService, 业 务 实 现 类 就 是 BookManagerImpl 或 者 BookServiceImpl 这 里 的 Impl 是 Implement 的 缩 写 对 于 一 些 工 具 类, 可 能 是 会 加 上 Utils, 比 如 FileUtils,StringUtils, 这 些 工 具 类 的 方 法 一 般 都 是 静 态 方 法, 比 较 著 名 的 org.apache.commons.lang, 下 面 有 很 多 工 具 类 如 果 是 异 常 类, 一 般 都 以 Exception 为 后 缀, 比 如 UniqueException, 一 看 名 称 大 概 就 是 这 个 一 个 违 反 唯 一 约 束 的 异 常 类 以 下 常 见 的 命 名 方 法 : org.hibernate.criteria javax.servlet.http.httpsession org.apache.tapestry.util.contenttype org.apache.commons.lang.stringutils org.springframework.dao.dataintegrityviolationexception 1.3 变 量 的 命 名 变 量 以 名 词 或 名 词 短 语 组 成, 第 一 个 英 文 字 母 必 须 小 写 如 果 是 静 态 变 量, 则 全 部 大 写, 用 下 滑 划 线 分 割 禁 止 在 名 称 中 出 现 形 容 词 动 词 和 动 词 衍 生 形 式 实 例 的 名 称 尽 量 用 类 的 名 字 或 者 有 意 义 的 英 文 单 词, 比 如 User user 和 UserService userservice 严 禁 使 用 无 意 义 的 字 母 活 数 字, 如 3

a,b,c,x,y,a1,a2,mynode,mytree 来 命 名 如 果 是 实 例 结 合 或 数 组, 那 一 般 用 类 名 的 复 数 形 式 或 者 后 缀 加 上 list 和 map, 比 如 userlist,usermap,users, 尽 量 避 免 直 接 用 map,list 作 为 实 例 名 称 常 见 的 命 名 方 法 : byte[] buffer public static final int INDEX = 0 private final boolean iscascadedeleteenabled; EntityKey key = new EntityKey() 1.4 参 数 的 命 名 参 数 的 名 字 和 变 量 的 命 名 规 范 一 致 1.5 数 组 的 命 名 数 组 应 该 总 是 用 下 面 的 方 式 来 命 名 : byte[] buffer; 而 不 是 : byte buffer[]; 1.6 方 法 的 命 名 方 法 的 命 名 以 动 词 和 动 词 短 语 组 成, 第 一 个 英 文 字 母 必 须 小 写, 但 有 一 个 例 外, 以 is 和 has 为 前 缀 的 方 法 名 方 法 名 尽 量 让 客 户 程 序 员 看 见 名 称 就 大 概 知 道 这 个 4

方 法 的 行 为 Is 和 has 为 前 缀 的 方 法 返 回 的 都 是 boolean 或 Booelan. 常 见 的 方 法 命 名 : protected boolean haspostcommiteventlisteners() private static EntityPersister create() publicboolean isadmin() 2. 文 件 样 式 2.1 Package/Imports Package 行 要 在 import 行 之 前,import 中 标 准 的 包 名 要 在 本 地 的 包 名 之 前, 而 且 按 照 字 母 顺 序 排 列 禁 止 使 用 * 方 式, 如 java.io.* 导 入 定 义 应 当 是 类 的 全 称 import java.util.arraylist; import java.util.hashtable; 2.2 类 和 接 口 类 和 接 口 需 要 填 写 注 释, 一 般 是 用 来 解 释 类 的 职 责 和 使 用 方 法, 而 且 要 尽 可 能 的 详 细 /** * A class representing a set of packet and byte counters * It is observable to allow it to be watched, but only * reports changes when the current set is complete * @author Ken */ 5

public interface UserDao extends GenericDao<User, Long> 2.3 成 员 变 量 public 的 成 员 变 量 必 须 要 有 注 释 proceted private 成 员 变 量 如 果 名 字 含 义 明 确 的 话, 可 以 没 有 注 释 /** * Packet counters */ protected int[] packets; 2.4 构 造 函 数 构 造 函 数 应 该 用 递 增 的 方 式 写 ( 比 如 : 参 数 多 的 写 在 后 面 ) 访 问 控 制 符 ("public", "private" 等.) 和 任 何 "static", "final" 或 "synchronized" 应 该 在 一 行 中, 并 且 方 法 和 参 数 另 写 一 行, 这 样 可 以 使 方 法 和 参 数 更 易 读 public counterset(int size){ this.size = size; } 2.5 方 法 接 口 的 方 法 默 认 是 public, 定 义 接 口 方 法 可 以 不 定 义 访 问 控 制 符 号 类 的 方 法 必 须 指 定 访 问 控 制 符 所 有 的 方 法 必 须 写 方 法 注 释, 但 接 口 和 抽 象 类 的 实 现 方 法 可 以 不 写 6

3. 编 程 惯 例 3.1 public private final protected 使 用 任 何 一 个 类, 接 口, 方 法, 变 量 必 须 要 有 访 问 控 制 符 号, 如 果 是 提 供 给 客 户 程 序 使 用, 那 么 申 明 为 public, 如 果 只 是 内 部 过 渡 行 为, 那 么 申 明 为 private. 这 里 有 一 个 原 则, 尽 量 使 用 private, 少 使 用 public. 3.2 代 码 中 不 能 出 现 无 用 的 包 和 类 变 量 具 体 到 Eclipse 工 作 区 内 禁 止 出 现 任 何 红 色 错 误 和 黄 色 警 告 的 标 记 出 现 3.3 禁 止 在 一 个 Java 文 件 中 编 写 多 个 类 匿 名 类 除 外, 但 建 议 少 用 3.4 继 承 一 般 只 能 继 承 抽 象 类 且 不 能 超 过 两 层 继 承 继 承 非 抽 象 类, 重 载 了 非 抽 象 方 法, 在 实 例 的 向 上 转 型 和 向 下 转 型 会 带 来 一 些 意 想 不 到 的 困 扰, 建 议 经 验 不 足 者 慎 用 继 承 是 一 种 无 契 约 无 保 证 的 方 法 重 用, 父 类 方 法 行 为 的 改 变 不 会 通 知 到 子 类 和 子 类 的 客 户 程 序 多 用 接 口, 少 用 继 承 7

3.5 if, if-else, if else-if else 语 句 (if, if-else, if else-if else Statements) if-else 语 句 应 该 具 有 如 下 格 式 : if (condition) { statements; } else if (condition) { statements; } else{ statements; } 注 意 :if 语 句 总 是 用 "{" 和 "}" 括 起 来, 避 免 使 用 如 下 容 易 引 起 错 误 的 格 式 : if (condition) statement; 3.5 while,if, for, 相 互 嵌 套 的 层 次 不 能 超 过 3 层 while(true){ if(size > 0){ for(user user : userlist){ if(user.name.isempty()){.. } } } } 8

3.6 java 代 码 中 不 能 出 现 SQL 和 HQL SQL 和 HOL 在 Java 代 码 中 很 难 排 版 和 维 护, 禁 止 在 代 码 中 出 现 String sql = "select c.* from metaone_dclass "; Session session = getsession(false); Query query = session.createsqlquery(sql).addentity(dclass.class); query.setparameter("id", id); return query.list(); 3.7 禁 止 直 接 在 控 制 台 打 印 禁 止 使 用 System.out.* 和 System.error.*,e.printStackTrace() 请 使 用 Log4j 来 处 理 3.8 Collection 和 Map 之 间 尽 可 能 避 免 相 互 嵌 套, 禁 止 相 互 嵌 套 超 过 一 层 Map<String, Map<? extends Object, Map<Integer, Object>>> authorities = authorization.getauthorities(); 3.9 方 法 参 数 的 个 数 禁 止 超 过 3 个 public List<DClass> finddclass(string dclassname, List<DAttribute> attributes, Long mclassid, int firstresult, int maxresults, boolean matchcase) 9

3.10 import 的 类 不 能 超 过 30 个 此 项 作 为 建 议 3.11 页 宽 限 制 页 宽 应 该 设 置 为 80 字 符 源 代 码 一 般 不 会 超 过 这 个 宽 度, 并 导 致 无 法 完 整 显 示, 但 这 一 设 置 也 可 以 灵 活 调 整 在 任 何 情 况 下, 超 长 的 语 句 应 该 在 一 个 逗 号 或 者 一 个 操 作 符 后 折 行 一 条 语 句 折 行 后, 应 该 比 原 来 的 语 句 再 缩 进 2 个 字 符 3.12 {} 对 限 制 {} 中 的 语 句 应 该 单 独 作 为 一 行. { 应 当 在 一 行 的 结 束 出 现, 不 出 现 在 新 行 开 始, 应 当 在 一 个 新 行 中 开 始 和 结 束, 即 使 代 码 体 中 只 有 一 行, 也 需 要 使 用 {} 例 如, 下 面 的 第 1 行 是 错 误 的, 第 2 行 是 正 确 的 : 错 误 范 例 if (i>0) { i ++ }; 正 确 范 例 if (i>0) { i ++ }; 10

3.13 类 代 码 长 度 和 方 法 代 码 长 度 每 个 Java 程 序 一 般 不 的 超 过 200 行, 每 个 Java 方 法 一 般 不 的 超 过 50 行 如 果 超 过 类 超 过 200 行, 方 法 超 过 50 行, 那 就 需 要 重 新 审 查 一 下 设 计, 类 的 职 责 是 否 单 一, 方 法 是 否 承 载 的 过 多 的 功 能 臃 肿 的 类 和 方 法 的 出 现, 一 般 都 伴 随 的 相 同 或 相 似 的 代 码 出 现 如 果 出 现 了 相 同 和 相 似 的 代 码, 那 么 就 需 要 的 相 同 的 代 码 抽 象 出 来 成 一 个 独 立 的 类 或 方 法 3.14 代 码 禁 止 出 现 TODO 这 些 代 码 一 般 都 是 IDE 自 动 生 成 4. 注 释 规 范 注 释 主 要 是 用 于 描 述 类 的 职 责, 方 法 的 行 为 注 释 应 被 用 来 给 出 代 码 的 总 括 并 提 供 代 码 自 身 没 有 提 供 的 附 加 信 息 注 释 应 该 仅 包 含 与 阅 读 和 理 解 程 序 有 关 的 信 息 禁 止 在 代 码 中 出 现 到 此 一 游 的 想 象, 比 如 在 代 码 中 注 释 某 人 在 某 时 做 某 事, 这 部 分 注 释 内 容 应 该 提 交 到 版 本 管 理 工 具 中 11

建 议 : 尽 可 能 避 免 注 释 单 行 和 在 方 法 内 部 写 注 释 比 如 String password;// 密 码 如 果 需 要 注 释 请 重 新 审 视 变 量 的 命 名 如 果 需 要 在 方 法 内 部 写 注 释, 请 重 新 检 查 方 法 的 注 释 是 否 足 够 详 细 或 者 方 法 的 设 计 是 否 存 在 问 题 注 意 : 频 繁 的 注 释 有 时 反 映 出 代 码 的 低 质 量 当 你 觉 得 被 迫 要 加 注 释 的 时 候 考 虑 一 下 重 写 代 码 使 其 更 清 晰 4.1 范 例 Java 的 注 释 :/**... */ 注 释 若 干 行, 并 写 入 javadoc 文 档 注 释 要 简 单 明 了, 边 写 代 码 边 注 释, 修 改 代 码 同 时 修 改 相 应 的 注 释, 以 保 证 注 释 与 代 码 的 一 致 性 在 必 要 的 地 方 注 释, 注 释 量 要 适 中 注 释 的 内 容 要 清 楚 明 了, 含 义 准 确, 防 止 注 释 二 义 性 在 每 个 源 文 件 的 头 部 要 有 必 要 的 注 释 信 息, 包 括 : 版 本 号 ; 作 者 ; 生 成 日 期 ; 模 块 功 能 描 述 ( 如 功 能 主 要 算 法 内 部 各 部 分 之 间 的 关 系 该 文 件 与 其 它 文 件 关 系 等 ) 比 如 : /** * This class can be used to parse other classes containing constant definitions * in public static final members. The <code>asxxxx</code> methods of this class 12

* allow these constant values to be accessed via their string names. * * @author Rod Johnson * @author Juergen Hoeller */ 4.2 Null 规 约 如 果 方 法 允 许 Null 作 为 参 数, 或 者 允 许 返 回 值 为 Null, 必 须 在 JavaDoc 中 说 明 如 果 没 有 说 明, 方 法 的 调 用 者 不 允 许 使 用 Null 作 为 参 数, 并 认 为 返 回 值 是 Null Safe( 不 会 返 回 NULL) /** * 获 取 对 象. * * @ return the object to found or null if not found. */ pubic Object get(integer id){... } 4.3 注 释 标 签 语 法 @author 对 类 的 说 明 标 明 开 发 该 类 模 块 的 作 者 @version 对 类 的 说 明 标 明 该 类 模 块 的 版 本 @see 对 类 属 性 方 法 的 说 明 参 考 转 向, 也 就 是 相 关 主 题 13

@param 对 方 法 的 说 明 对 方 法 中 某 参 数 的 说 明 @return 对 方 法 的 说 明 对 方 法 返 回 值 的 说 明 @exception 对 方 法 的 说 明 对 方 法 可 能 抛 出 的 异 常 进 行 说 明 14