JAVA代码编写规范

方正春元科技发展有限公司方正春元科技发展有限公司 Java 代码编写规范代码编写规范 文档编号 文档编号 FOUNDERCY MD SPECIFICATION 31 1 0 编写 吴显富日期 2003 5 27 审批 曾纪才日期 2003 5 29 受控状态 是 否 发布日期 2003 5 29 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 文件修改记录表文件修改记录表 修改内容要点修改内容要点修改时间修改时间修改人修改人审批人审批人 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 i 目目 录录 1 引言引言 1 1 1编写目的 1 1 2适用范围 1 1 3引用标准 1 1 4参考资料 1 2 基本概念基本概念 2 2 1规范的重要性 2 2 2模块开发卷宗 2 2 2 1源程序文件与模块 3 2 2 1 1源程序文件 3 2 2 1 2模块 3 2 2 1 3源程序文件与模块的关系 3 2 2 2模块开发卷宗的组成 4 2 2 2 1基本要求 4 2 2 2 2Java 的注释类型在本规范中的映射 4 2 2 2 3Javadoc 及其文档标记 5 3 JAVA 注释规范注释规范 7 3 1一般原则 7 3 2源程序文件头注释 7 3 2 1编写过程 7 3 2 2内容 7 3 2 2 1强制性条目 7 3 2 2 2可缺省条目 8 3 2 3形式审查 8 3 3模块 类 注释 9 3 3 1编写过程 9 3 3 2内容 9 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 ii 3 3 2 1强制性条目 9 3 3 2 2可缺省条目 9 3 3 3形式审查 10 3 4段注释 11 3 4 1编写过程 11 3 4 2内容与示例 11 3 4 2 1属性注释 11 3 4 2 2方法注释 12 3 4 2 3异常注释 13 3 5行尾注释 13 3 5 1编写过程 13 3 5 2内容 13 4 JAVA 命名规范命名规范 14 4 1一般原则 14 4 2接口 类 编译单元 包的命名 14 4 2 1接口命名 14 4 2 2类命名 15 4 2 3包命名 15 4 2 4编译单元命名 15 4 3属性命名 16 4 3 1一般约定 16 4 3 2组件的命名 16 4 3 3常量的命名 16 4 3 4集合的命名 17 4 4方法命名 17 4 4 1一般约定 17 4 4 2存取方法命名 accessors 17 4 4 2 1获取方法 getters 18 4 4 2 2设置方法 setters 18 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 iii 4 4 2 3构造方法 18 4 5方法参数命名 19 4 6局部变量命名 19 4 6 1流的命名 19 4 6 2循环计数器的命名 19 4 6 3异常对象的命名 20 5 JAVA 编码规范编码规范 20 5 1类的编码规范 20 5 1 1类的可见性 20 5 1 2对属性和方法进行排序 20 5 2属性的编码规范 21 5 2 1属性的可见性 21 5 2 2对属性的访问 21 5 3方法的编码规范 21 5 4局部变量的编码规范 22 5 5用于测试的编码规范 22 6 JAVA 编码优化编码优化 23 7 JSP 规范规范 25 7 1JSP文件存放 25 7 2JSP文件名 25 7 3JSP目录名称与结构 25 7 4JSP其他规范 26 附录一 名词与术语解释附录一 名词与术语解释 26 附录二 附录二 JAVADOC 的使用的使用 28 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 1 页 共 30 页 1 引言引言 1 1 编写目的编写目的 本文档是关于 Java 编程的规范性文件 主要内容是规范 Java 编程过程中代 码编写 注释编写 模块开发卷宗生成等工作 目前版本是 Ver1 0 Java 是基 于 Internet 的跨平台的编程语言 与传统的编程语言 C C Basic 等 相比 有不少独特性的内容和要求 因此本规范初步设计将经过征求意见 试用 定 稿等阶段 最后批准执行 定稿以后的规范也将在适当时间进行版本升级和内 容更新 1 2 适用范围适用范围 JAVA 编码人员和相关部门技术管理人员和品质保证部 1 3 引用标准引用标准 1 中华人民共和国标准 软件工程术语 GB T11457 1995 2 中华人民共和国标准 信息技术 软件生存期过程 GB T8566 1995 3 中华人民共和国标准 计算机软件产品开发文件编制指南 GB T8567 1988 1 4 参考资料参考资料 1 Java 代码编写规范 2 可用 javadoc 直接生成的 Java 程序注释写法规范 3 如何写出稳健的 Java 代码 曹淼译 2000 9 30 原文 Writing Robust Java Code Scott W Ambler 2000 1 15 4 Java 编程思想 Thinking in JAVA 京京工作室译 原著 Bruce Eckel 机械工业出版社 2000 4 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 2 页 共 30 页 2 基本概念基本概念 2 1 规范的重要性规范的重要性 用于 Java 的编码规范之所以重要是因为它们可以使开发团队的代码中产生 较好一致性 好的一致性可产生较容易理解的代码 它也意味着代码容易开发 和维护 这将减少开发工作的全部成本 模块开发卷宗是软件文档与程序的结合 是由软件设计通往软件实现的桥 梁 同时具有文档类产品与程序类产品的双重属性 模块开发卷宗是程序 是带有规范化注释的源程序 能直接生成可运行 的程序代码 模块开发卷宗又是软件设计的延伸 是一卷可印刷 可阅读的文档 是 最详细的设计说明 是自顶向下 Top Down 软件设计描述 概要设计说明书 详细说明书 模块设计说明书 的终点 综上所述 无论从编写规范的 Java 代码的角度 还是从按软件工程生成模 块开发卷宗的角度来看 本规范是绝对需要的 2 2 模块开发卷宗模块开发卷宗 提起软件开发似乎就是编程序 写代码 模块开发卷宗好像是个新概念 实际上 模块开发卷宗 Module Development Folder 是 80 90 年代普遍采用的 一类软件中间产品形式 在传统的软件工程管理中起重要作用 至今仍在使用 本规范中 模块开发卷宗主要包括两部分 具备完整注释的源程序文件 由 Javadoc 生成的 HTML 文件 在软件配置计划中 将具备完整注释的源程序 列为程序类软件中间产品 将 Javadoc 生成的 HTML 文件列为文档类中间产品 另外 为了开发小组之间的交流和工作同步 还需要按照 代码说明规范 完 成一定的说明文档 此说明文档与模块开发卷宗有一定的重叠 但是必须的 说明文档也列为文档类中间产品 程序 模块 编码实现时的一个原则是 先写注释 后编码 目前情况 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 3 页 共 30 页 代码中的注释按照本规范手工输入 然后使用工具 Javadoc 生成 HTML 文件 2 2 1 源程序文件与模块源程序文件与模块 针对 Java 语言的具体情况 这里对 源程序文件 和 模块 即软件模 块 这两个术语加以特别说明 2 2 1 1源程序文件源程序文件 在基于 Java 语言的软件工程中 一个源程序文件就是一卷模块开发卷宗 在软件配置管理系统中 源程序文件是用于配置管理的程序单元 是列入 软件配置计划的程序类软件配置项 SCI 2 2 1 2模块模块 软件模块简称模块 module 在国家规范 1 中 模块一词有两种解释 a 是离散的程序单位 且对于编译 对于和其他单位相结合 对于装入来 说是可识别的 例如 汇编程序 编译程序 连接编辑程序或执行的例行程序 的输入或输出 b 程序中一个能逻辑地分开的部分 在本规范中选用上述第二种解释 一般的说 一个模块实现一定的功能 或提供一定的服务 或一组数据 具体到 Java 语言的程序设计中 模块是一组用户定义类 Class 的声明 2 2 1 3源程序文件与模块的关系源程序文件与模块的关系 在 Java 语言中 原则上一个源程序文件包含一个软件模块 Class 软件工程中软件的配置管理只管到源程序文件级 而不深入到文件内部去 管理模块 与此相反 在设计文档种 却必须包括对模块的描述 由此可见 程序类软件产品 包容 源程序文件 源程序文件 包容 模块 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 4 页 共 30 页 2 2 2 模块开发卷宗的组成模块开发卷宗的组成 2 2 2 1基本要求基本要求 本规范中要求在源程序文件中编写下面四种注释语句 即可满足模块开发 卷宗的要求 1 源程序文件头注释 Source file header 又称源程序文件前言 Preface 模块开发卷宗以源程序文件为单位 每一个源程序文件必须有一份 头注释 放在源程序文件的开头 对整个源程序文件加以说明 2 模块注释 Module comment 在 Java 语言中可以成为类注释 模块 注释是模块开发卷宗的核心 每一个模块都必须编写模块注释 模块注释放在 该模块的前面 3 段注释 Segment comment 又称块注释 Block comment 是插在 模块内部的一些说明 在 Java 语言中 主要使用段注释对类的属性 又称域 成员变量 字段 field 和方法 又称成员函数 method 进行注释 本规范 要求必须编写段注释 放在该段的前面 4 行尾注释 End of line comment 简称行注释 Line comment 是 对该行程序的简短解释 必要时才编写 放在程序行的后面 在模块开发卷宗中 四种注释的重点是不同的 源程序文件头注释主要面向配置管理 模块注释对模块做全面说明 特别强调描述模块结构 段注释着眼于详细描述代码运行过程 行注释辅助解释个别代码点 本规范中 源程序头注释 模块注释和段注释是强制的 即不可缺省的 而且 对强制性注释还规定了强制性条目 其他注释内容则是可缺省的 2 2 2 2Java 的注释类型在本规范中的映射的注释类型在本规范中的映射 Java 有三种注释类型 文档类型 C 类型和单行注释 文档类型 以 开始 而以 结束 可以由 Javadoc 自动处理 例 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 5 页 共 30 页 如 Customer A customer is anyperson or organization that wesell services and products to author S W Ambler C 类型 以 开始 而以 结束 例如 This code was commented outby J T Kirk on Dec 9 1997 because it was replaced by thepreceding code Delete it after two years if it is still not applicable the source code 单行注释 以 开始 直到源代码行的结束 例如 Apply a 5 discount to all invoices over 1000 as defined by the Sarek generosity campaign started in Feb of 1995 在本规范中 头注释 模块注释和段注释使用文档类型编写 并且使用一 定的 Javadoc 文档标记 Doc tags 行尾注释的编写原则不限制使用何种类型 一般使用单行注释 2 2 2 3Javadoc 及其文档标记及其文档标记 在 SUN 的 Java 开发工具包 JDK 中含有一个称为 javadoc 的程序 它处 理 Java 源程序文件 并且以 HTML 的形式产生一个外部文档 类似联机帮助 文档 javadoc 主要通过两种方式生成 HTML 文档 嵌入的 HTML 或使用 文档标记 其中 文档标记 Doc tags 是一些以 开头的命令 置 于注释行的起始处 但前导的 会被忽略 所有 javadoc 文档标记只能出 现于 Java 文档类型注释中 实际上文档标记总是和 HTML 标记混合使用的 在本规范中就是混合使用的 主要是使用 HTML 标记 实现注释文字的 换行 具体使用样例参看下文 本文档中使用 文档标记 对源程序进行相应注释 javadoc 只能为 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 6 页 共 30 页 public 公共 和 protected 受保护 成员处理注释文档 private 私有 成 员的注释一般会被忽略 我们看不到任何输出 Javadoc 目前版本使用的 文档标记 见表 1 文档标记 的具体使用见 本规范的第三部分 表 1 javadoc 文档标记 一览表 文档标记功能 author 作者信息 作者信息 包括作者的姓名 电子函件地 址或者其他任何适宜的资料 可为一系列作者使 用多个这样的标记 但它们必须连续放置 deprecated 该标记用于指出一些旧功能已由改进过的新 功能取代 该标记的作用是建议用户不必再使用 一种特定的功能 因为未来改版时可能摒弃这一 功能 若将一个方法标记为 deprecated 则使用 该方法时会收到编译器的警告 exception 完整类名 说明 异常 注释 简言之 它们是一些特殊的 对象 若某个方法失败 就可将它们 扔出 对 象 完整类名 明确指定了一个异常类的名字 它是在其他某个地方定义好的 而 说明 同 样可以延续到下面的行 告诉我们为什么这种特 殊类型的异常会在方法调用中出现 param 参数名 说明 参数名 是指参数列表内的标识符 而 说明 代表一些可延续到后续行内的说明文字 一旦遇 到一个新文档标记 就认为前一个说明结束 可 使用任意数量的说明 每个参数一个 return 说明 说明 是指返回值的含义 它可延续到后面 的行内 since此标记表示自从什么版本开始有效 see 类名 在生成的文档里自动加入一个超链接的 See Also 参见 条目 注意 javadoc 不会检查我们 指定的超链接 不会验证它们是否有效 see 类名 方法名同上 version 版本信息 版本信息 代表任何适合作为版本说明的资 料 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 7 页 共 30 页 3 Java 注释规范注释规范 3 1 一般原则一般原则 注释是为了使代码更清楚 如果源程序不值得写文档 注释 它就不值得运行 避免空洞的注释 注释要简单 先写注释后编程 即要注释 做什么 也要注释 为什么这样所 3 2 源程序文件头注释源程序文件头注释 3 2 1 编写过程编写过程 源程序文件头注释描述整个文件 而且描述是逐次完成的 源程序文件作 为软件系统的程序配置项 一般在编写系统配置计划时予以定义 并赋予唯一 的配置项代号 因而 文件头注释的前几行 名称 配置项代号等 可有软件 配置计划直接导出 并作为编写该程序文件的进入条件 源程序文件作者补齐 头注释的内容 例如 源程序文件的版本号 形成完整的头注释 在源程序文 件提交之前再对头注释做最后敲定 3 2 2 内容内容 3 2 2 1强制性条目强制性条目 源程序文件头注释是面向配置管理的 通常不是面向软件详细设计的 在 Java 语言编程实践中 一般是一个源程序文件对应一个类 模块 从这个意义 上说 Java 源程序文件头注释与软件详细设计也具有一定的关系 针对 javadoc 的处理原则 完整的源程序文件头注释至少包括 2 个条目 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 8 页 共 30 页 源程序文件名称 标题 软件配置项代号 在软件工程尚不完善时 此项暂空缺 3 2 2 2可缺省条目可缺省条目 除上述强制性条目外 视具体情况可适当增加其他注释内容 例如 源程序文件摘要 说明该程序的用途等 环境要求 操作系统 编译器 Debugger 库 等等 与老版本的差别 这里只说明被修改的程序行位置 具体修改 内容由后续的注释描述 其他需要说明的事项 例如文件背景 与其他源程序文件的参 考关系 3 2 3 形式审查形式审查 1 配置管理员 CM 阅读源程序文件头注释 进行该配置项与相关配 置项的形式匹配 源程序级 2 质量保证人员 QA 对源程序文件头注释进行形式审查 首先检查 强制性条目是否有遗漏 然后检查内容是否正确 3 Java 源程序文件头注释强制性条目示例如下 注意 和的混合使 用 GeoMap java SCI NULL 4 注释即可以使用英文也可以使用中文 为了阅读的方便 本规范混合 使用两种语言 如上所示 其他注释的语言使用参照执行 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 9 页 共 30 页 3 3 模块 类 注释模块 类 注释 3 3 1 编写过程编写过程 软件系统由若干模块 类 组成 各模块 类 已由软件详细设计说明书 定义 并赋予唯一的标示符 因而 模块 类 注释的前几行已经由软件设计 师草拟 所以模块 类 注释的前几行可从软件详细设计说明书中导出 完整的模块 类 注释由程序员编写 在源程序文件作为软件配置项提交 前 对模块 类 注释内容作最后敲定 针对 javadoc 的处理原则 本规范中 对模块 类 注释做强调要求 注释详细 注释项多 3 3 2 内容内容 3 3 2 1强制性条目强制性条目 模块开发卷宗是软件设计的终点 应该与软件详细设计说明书有适当的重 复 以下条目是模块 类 注释的强制性条目 类名称 公司的软件版权声明 英文 中文 类功能 类完成的处理或功能 源程序文件提交日期 源程序文件版本历史 版本号 源程序文件作者或维护者 使用的 JDK 版本 3 3 2 2可缺省条目可缺省条目 除上述强制性条目外 视具体情况可适当增加其他注释内容 例如 同步策略 任何实现接口 Runnable 的类应该具有完整描述的同 步策略 包括以下几点 Synchronized objects balking objects guarded 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 10 页 共 30 页 objects versioned objects concurrency policy controllers 以及 acceptors 参考条目 测试信息 限制 模块可用范围或边界 已知的副作用 Side effect 对其他类或数据的潜在影响 3 3 3 形式审查形式审查 QA 对模块开发卷宗的模块注释进行形式审查 一方面阅读源程序检查强 制性条目是否有遗漏 一方面阅读 javadoc 生成的 HTML 文档进行相关检查 内容是否完整 链接是否正确等 Java 类注释强制性条目示例如下 注意 和的混合使用 动态创建查询结果显示面板类 Copyright 2000 by Digiark Software corporation All rights reserved 版权所有 方正春元科技发展有限公司 未经本公司许可 不得以任何方式复制或使用本程序任何部分 侵权者将受到法律追究 DERIVED FROM NONE PURPOSE WebGIS 界面上 动态创建查询结果显示面板 响应区域 查询操作 DESCRIPTION 面板上共有七个组件 Label 4 Choice List Button CALLED BY ArkGis UPDATE Sun Hongjun 孙洪君 DATE 2000 年 10 月 30 日 HISTORY 1 0 version 1 0 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 11 页 共 30 页 author Sun Hongjun 孙洪君 since java 1 3 0 C see ArkGis see MapArea public class AreaQueryResultDisPanel extends Panel 3 4 段注释段注释 3 4 1 编写过程编写过程 Java 源程序文件以类为单位进行组织 所以 段 的概念有一些转化 属 性 属性 声明 方法声明 特殊 异常 声明以及方法内的完整语义段都可 以作为 段 段注释都写在该段程序行的前面 占用一行或若干行 段注释由程序员编写 本规范要求 程序员应先规划好类的相应 段 写 出各段注释 然后再编程 在编程过程中 只要必要 随时插入段注释 对程 序要点进一步说明 在源程序文件提交之前再对各段注释作最后检查 3 4 2 内容与示例内容与示例 3 4 2 1属性注释属性注释 对于一些意义很明显的属性不用注释 写法示例 图名 protected String mapName 所用图符 不序列化 接收 GeoMap 后应从 pixels 生成 protected transient Image icons 保存图符的原始数据 protected byte pixels 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 12 页 共 30 页 3 4 2 2方法注释方法注释 方法注释说明方法的要点 逻辑 算法或数据含义 等 是程序作者或读 者在阅读这段程序时 不必在自己的头脑中仿真运行代码的执行过程 本规范给出方法注释的几个内容选项 程序员可以视情况选用 方法功能说明 必需 方法实现逻辑 可选 方法参数 可选 方法返回值 可选 方法涉及的数据 可选 方法的修改维护历史说明 何时修改 修改人员等 可选 方法的缺陷 bugs 可选 方法的所有异常 可选 方法可见性设置的原因 可选 一个方法如何改变一个对象 可选 激活方法的例子 可选 应用前提和后置条件 可选 并发性说明 可选 写法示例 地图对象构造函数 param mapName 图名 public GeoMap String mapName this mapName new String mapName roundRect new GeoTRect viewRect new GeoTRect layerList new Vector 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 13 页 共 30 页 取图名称 return 图名 public String getName return mapName 3 4 2 3异常注释异常注释 写法示例 exception IOException 若有错误输入或输出便抛出 IO 异常 public void f throws IOException body 3 5 行尾注释行尾注释 3 5 1 编写过程编写过程 源程序文件由若干程序行组成 每一行可能有完整的语义 也可能没有完 整的语义 行尾注释由程序员在编程或维护时随时插入的 所以行尾注释通常 是 先编程 后注释 行尾注释不单独占用一行 而是附在同一行的后面 如 果行尾注释长度超出一行 最好不要写在续行上 而应该为段注释 移到这行 的前面 3 5 2 内容内容 行尾注释是对程序中的 一点 进行说明 以便进一步改善程序的可读性 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 14 页 共 30 页 有利于代码的走查 Walk through 有利于程序的理解与软件维护 行尾注释具有非常大的任意性 提倡程序员在程序行后附加足够的注释 但并非越多越好 行尾注释必须能对程序的理解增加新的信息 对于那些已清 楚地自说明的行 附加注释是没有意义的 例如 下列情形均由必要插入行尾注释 对语句地用途进行附加说明 例如 调用 XX 方法 多线程通信中地加锁 Lock 和解琐 Unlock 在多层嵌套判断结构中 一层的结束行 例如 XX 循环结束 模块 类 结束行 例如 XX 模块 类 结束 源程序文件结束行 例如 XX 文件结束 4 Java 命名规范命名规范 4 1 一般原则一般原则 使用完整的英语描述 使用符合专业领域术语 使用混合大小写增强可读性 在保证可读性的情况下 使用简写方式 避免长名字 最好在15字符以内 避免出现仅仅是大小写不同的两个变量名字 4 2 接口 类 编译单元 包的命名接口 类 编译单元 包的命名 4 2 1 接口命名接口命名 接口 使用 interface 关键字 可以认为是一个 纯 抽象类 它允许创 建者规定一个类的基本形式 方法名 自变量列表以及返回类型 但不规定方 法主体 接口也包含了基本数据类型的数据成员 但它们都默认为 static 和 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 15 页 共 30 页 final 接口只提供一种形式 并不提供实施的细节 接口这样描述自己 对 于实现我的所有类 看起来都应该象我现在这个样子 接口的命名 每个单词的首字母为大写 且命名英文混合大小写 本规范 规定接口命名利用一个可描述的形容词 如 Runnable 或 Cloneable 等 4 2 2 类命名类命名 类的命名 每个单词的首字母为大写 且命名英文混合大小写 例如 Customer Employee Order OrderItem FileStream String 4 2 3 包命名包命名 包是一个相关类的集合 有几个涉及包命名的规则如下所示 1 包名称以英文句号分割标示符 标示符全部为英文小写 SUN 公司 建议包中的标示符由英文句号来分割 例如 java awt 2 来自 SUN 公司的标准的 java 分布包是以标示符 java 和 javax 开始的 3 局部包的名称以一个并非全部为大写的标示符开始 局部包是用于你 的部门内部的 并且将不被分发给其它部门 例如 persistence mapping relational 和 interface screen 4 将要分发给多个部门的一个包 全局包 名称中应该包括源部门的 域名 顶级域名小写 例如 com ambysoft www persistence mapping relational 和 com ambysoft www interface screens 5 包的命名应该是单数 常用的规范是利用单一的名称对包进行命名 如 interface screen 而不是复数 如 interface screens 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 16 页 共 30 页 4 2 4 编译单元命名编译单元命名 一个编译单元就是一个源程序文件 但是这个源程序文件包含两个或者两 个以上的类或接口 本规范建议 尽量不使用编译单元 使用编译单元中所定 义的接口或类的名称对编译单元命名 且大小写相同 例如 Customer java Singleton java SavingsAccount java 4 3 属性命名属性命名 4 3 1 一般约定一般约定 本规范中属性使用全英文进行命名 一般情况是所有单词都小写 单词之 间以下划线 分开 例如 first name zip code unit price discount rate order items sql database 4 3 2 组件的命名组件的命名 对于图形化用户界面 组件 按钮 菜单等 是必不可少的 本规范中 组件以 组件功能 组件类型 的方式进行命名 例如 okButton customerList fileMenu newFileMenuItem 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 17 页 共 30 页 4 3 3 常量的命名常量的命名 在 Java 中 常量的值不发生变化 是典型的类的静态终止 static 或 final 属性 常量的命名标准是使用全部大写的英文单词 单词之间使用下划 线连接 例如 MINIMUM BALANCE MAX VALUE DEFAULT START DATE 4 3 4 集合的命名集合的命名 集合 如序列或矢量 以集合类型的第一个字母开始 加上类名的复数形 式进行命名 例如 List lCustomers null Vector vOrderItems null 4 4 方法命名方法命名 4 4 1 一般约定一般约定 方法使用全英文描述来命名 并且 方法命名字符串中第一个词全部小写 以后其他各词首字符大写 另外 一个通常的规则是一个方法名的第一个词应 该是动词 例如 openAccount printMailingLabel save delete 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 18 页 共 30 页 4 4 2 存取方法命名 存取方法命名 accessors 存取方法用来获取和设置类属性值 存取方法的命名规则概括如下 4 4 2 1获取方法 获取方法 getters 获取方法返回类的一个属性值 一般存在两种情况 属性为二态变量 属 性非二态变量 如果属性为二态变量 则获取方法的前缀是 is 如果属性非 二态变量 则获取函数的前缀是 get 例如 getFirst name getAccount number getLost eh isPersistent isAt end 4 4 2 2设置方法 设置方法 setters 设置方法也称为修改方法 它修改类的一个属性值 设置方法的前缀是 set 无论属性的类型是什么 例如 setFirst name String aName setAccount number int anAccountNumber setReasonable goals Vector newGoals setPersistent boolean isPersistent setAt end boolean isAtEnd 4 4 2 3构造方法构造方法 当一个对象 类 首先被创立时 构造方法完成任何必要的初始化 构造 方法总是与给定它们的类名相同 且大小写相同 例如 Customer SavingsAccount 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 19 页 共 30 页 PersistenceBroker 这个命名规则由 SUN 公司制订 并且必须严格遵守 4 5 方法参数命名方法参数命名 使用有意义的参数命名 如果可能的话 使用和要赋值的字段一样的名字 SetCounter int size this size size 4 6 局部变量命名局部变量命名 局部变量是在一个代码块范围内 如方法 定义的对象或数据条目 一个 局部变量的范围就是它所定义的数据块范围 在本规范中 局部变量原则上以与属性相同的规范进行命名的 即使用全 英文进行命名 且首单词全部小写 在编程实践中 有几个特定的局部变量类型 其命名约定比较特殊 下面 分别作以介绍 4 6 1 流的命名流的命名 当有一个单个的输入流或输出流在一个方法内被打开 被利用 然后被关 闭时 利用 in 和 out 对这些流命名 对于一个用于输入和输出两者的流 来说 它的名称就是 inOut 例如 inStream outStream inOut 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 20 页 共 30 页 4 6 2 循环计数器的命名循环计数器的命名 在本规范中 循环计数器通常以单个字母 i j 或者 k 进行命名 如果 i j k 不够使用时 可考虑适当扩展 如 ii jj kk 等 4 6 3 异常对象的命名异常对象的命名 异常处理在 Java 编码中是非常普通的问题 本规范中 对异常对象以单个 字母 e 进行命名 5 Java 编码规范编码规范 5 1 类的编码规范类的编码规范 5 1 1 类的可见性类的可见性 面向对象程序设计的基本特征之一就是使类的公共接口最小化 换句话说 这是关于类的可见性的问题 Java 中类的可见性定义有 public package 缺 省 意为友好访问 以及特别的 final public 类型的类对所有的其它的类都是 可见的 而 package 的却省类仅对同一包内的类是可见的 使用 final 定义的类 是不能被继承的 本规范建议在进行 Java 编程时必须认真考虑使类的公共接口最小化 5 1 2 对属性和方法进行排序对属性和方法进行排序 本规范要求以一种统一的方式对类的属性和方法进行声明 但具体方式不 作强制规定 这里给出本规范的一个建议 在类中以最容易访问到最不容易访 问的顺序对属性和方法进行声明 例如 private fields constructors finalize 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 21 页 共 30 页 public member functions protected member functions private member functions 5 2 属性的编码规范属性的编码规范 5 2 1 属性的可见性属性的可见性 本规范对属性的可见性有三个要求 1 所有的属性都以 private 进行声明 2 对于不一致的属性 它们将不会被永久的存储 把它们定义为静态 的 static 或暂时的 3 不要 隐藏 属性名称 5 2 2 对属性的访问对属性的访问 本规范中规定在编程实践中对属性的访问只有一个途径 就是通过存取方 法实现 这样做的目的是使类的封装性更好 举例如表 2 表 2 属性及存取函数举例 属性类型获取函数设置函数 first nameStringgetFirst ame setFirst name addressSurfaceAddress objectgetAddress setAddress persistentBooleansetPersistent setPersistent customer numberIntgetCustomer number setCustomer number order itemsArray of OrderItem objectgetOrder items setOrder items 关于 Java 中存取函数的高级技术可以参考参考文献 3 本规范不作强制性 规定 5 3 方法的编码规范方法的编码规范 一个好的设计应该使类之间的关联最小 这也是本规范的要求 当设计一 个方法的可见性时 本规范要求尽可能地先限制它 如果一个方法不必是公有 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 22 页 共 30 页 的 public 那么使它设置为保护的 protected 而如果不必被保护 那么就 设置它为私有的 private 表 3 是详细的分类解释 表 3 关于方法可见性定义的分类解释 可见性描述相应的用法 public一个公有方法能够被任何其它对象 或类的任何方法激活 当一个方法必须对继承类 中的外部对象或外部类可访问 时 定义该方法为public protected一个保护方法能够被类中的其它任 何方法以及其子类中的方法激活 当方法只提供给继承类中 方法访问时 定义该方法为 protected private私有方法仅能被本类中的其它方法 所激活 私有方法为类提供特定的 行为 通常对类的内部进行重 新整合 私有方法的作用范围 只限于类内部 包内缺省的 友员方法 表示没有任何可见性 这被称为缺 省或包可见性 并且有时被称为友 好的可见性 方法在同一个包内对 所有其它类都是有效公有的 但对 包的外部的类是私有的 当要建造域组件 Domain components 时应用该特征 如实现一个 Customer 的商 务概念集合 仅供组件或包中 的类进行限制访问 5 4 局部变量的编码规范局部变量的编码规范 关于局部变量的编码规范本规范有以下几点要求 1 不要 隐藏 局部变量 2 每行代码声明一个局部变量 3 在局部变量证明的同一行内对它进行注释 4 在使用局部变量的语句前面声明该局部变量 即声明局部变量之后马 上使用它 5 一个局部变量只做一个用途 5 5 用于测试的编码规范用于测试的编码规范 测试是软件开发过程中的必不可少的重要工作 关于测试的编码一般有两 种形式 一种是嵌入类内部的测试方法 一种是单独的测试类 本规范主要针 对编写测试代码时应遵循的准则制定一些要求 1 对所有测试方法的名称使用前缀 test 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 23 页 共 30 页 2 所有用于测试方法的测试方法名称要求保持一致 例如 测试 withdrawFunds 的测试方法将包括 testWithdrawFundsForInsufficientFunds 和 testWithdrawFundsForSmallWithdrawal 如果具有一系列测试 withdrawFunds 的方法 则应该编写一个称为 testWithdrawFunds 方法 以激活所有的测试方 法 3 所有用于测试类的测试方法名称要求保持一致 类测试是验证一个的 类完成所定义功能的手段 所有类测试方法应该以如下格式进行命名 testSelfForTestName 例如 测试 Account 类的测试方法命名为 testSelfForSimultaneousAccess 和 testSelfForReporting 4 创建一个用于激活类测试的 起点 编写一个称为 testSelf 的静态 方法 该方法激活所有类测试和方法测试的方法 5 按照注释要求对测试编码进行注释 6 在软件最终成型时 去掉所有不需要的测试编码 6 Java 编码优化编码优化 本规范的主旨是希望程序员通过遵循规范编写出稳健性的 Java 代码 以上 几部分已经对相应内容作了规范 这里就 Java 编码优化的问题提出一些建议 并不具有强制性 首先应该明确编码优化必须有具体目标 本规范指出在进行软件开发时开 发团队必须对开发的优先顺序进行规划 所谓开发优先顺序就是编码优化的顺 序目标 例如 开发团队应该就规模 速度 稳健性 安全性 可测试性 可 维护性 简单性以及可携带性等目标的优先顺序做出选择和规划 下面是一些可以直接选用的编码优化技术 1 对代码分段 对代码分段 缩进缩进 改善方法可读性的方法之一就是对代码进行分段和缩进 例如包含在大括 号 之内的代码形成一个代码块 对这个代码块进行适当的缩进 本规范 推荐使用 Space 键进行空格缩进 不赞成使用 Tab 键 缩进的大小为 3 4 个空 格 52392cfb949ccadd64a771dde2f596a1 pdf FOUNDERCY MD SPECIFICATION 31 1 0 第 24 页 共 30 页 2 对长语句分行和加标点 但一个语句过长时 可以考虑适当分行 例如 BankAccount newPersonalAccount AccountFactory createBankAccountFor currentCustomer startDate initialDeposit branch 注意第二行和第三行进行了一定的缩进 但仍可以明显看出它们是第一行 内容的一部分 同时第二行末的逗号紧跟参数之后 而不出现在第三行 3 在代码中适当使用空行在代码中适当使用空行 本规范建议使用一定空行将 Java 代码划分成小的或者容易读懂的部分 具 体量化指标是一个空行将逻辑代码组分开 两个空行将方法定义分开 举例如 表 4 表 4 代码中使用空行的举例 counter 1 grandTotal invoice total getAmountDue grandTotal Discounter discount grandTotal this counter 1 grandTotal invoice total getAmountDue grandTotal Discounter discount grandTotal this 4 遵循遵循 30 秒原则秒原则 30 秒原则指一个类的方法应该使程序员在 30 秒之内完全理解它是做什么 的 它为什么这样做以及它是怎样做的 如果阅读理解的时间超过 30 秒 说明 这段代码太难维护 应该进行改进 类似的一个原则是 一个方法的代码不应该长到超过一个屏幕 5 一行一个命令 命令行要求