Q-DTM 0059-2011 Java语言编程规范[1]111.doc

Q DTM 大唐移动通信设备有限公司企业标准大唐移动通信设备有限公司企业标准 Q DTM 0059 2011 Java 语言编程规范 2011 06 16 发布 2011 06 16 实施 大唐移动通信设备有限公司 发 布 Q DTM 0059 2011 I 目 次 前前 言言 II 1范围范围 1 2规范性引用文件规范性引用文件 1 3定义 符号和缩略语定义 符号和缩略语 1 4编程规范总则编程规范总则 1 5命名规则 命名规则 NAMING CONVENTIONS 2 6文件组织 文件组织 FILE ORGANIZATION 3 6 1定义文件的结构定义文件的结构 3 6 2目录结构目录结构 5 6 3其它其它 5 7程序板式程序板式 6 7 1空行空行 6 7 2代码行代码行 7 7 3代码行内的空格代码行内的空格 8 7 4对齐对齐 9 7 5长行拆分长行拆分 9 7 6注释注释 10 8编程规则和建议编程规则和建议 13 8 1表达式表达式 13 8 2声明和定义声明和定义 15 8 3整数数据类型及操作整数数据类型及操作 15 8 4浮点型浮点型 15 8 5布尔类型布尔类型 16 8 6变量变量 16 8 7类型转换类型转换 16 8 8常量常量 17 8 9控制流程控制流程 17 8 10 垃圾收集垃圾收集 19 8 11 错误处理错误处理 19 8 12 断言断言 19 8 13 类类 19 8 14 通用规则和建议通用规则和建议 20 8 15 LOG 打印格式打印格式 21 9代码文档格式代码文档格式 21 Q DTM 0059 2011 II 9 1文档内容的基本要求文档内容的基本要求 21 9 2属性相关的文档标签属性相关的文档标签 21 9 3类相关的文档标签类相关的文档标签 21 9 4函数应该包含的文档标签函数应该包含的文档标签 22 9 5其它注释标签其它注释标签 22 9 6包和综述注释包和综述注释 23 9 7常用注释链接标签常用注释链接标签 23 Q DTM 0059 2011 III 前 言 本标准是根据 GB T 1 1 2009 标准化工作导则 第 1 部分 标准的结构和编写 起草制订 本标准是参考 SUN 公司的 Java 编程规范 文档注释 API 生成规范制定 便于指导 Java 软 件研发人员进行规范代码的编写 本标准提出单位 大唐移动通信设备有限公司研发部 本标准批准单位 大唐移动通信设备有限公司质量部 本标准归口单位 大唐移动通信设备有限公司质量部 本标准起草单位 大唐移动通信设备有限公司研发部 本标准于 2009 年 12 月 25 日首次发布 2009 年 12 月 30 日开始实施 本标准于 2011 年 05 月 13 日第 2 次修订 2011 年 06 月 16 日发布 2011 年 06 月 16 日开始实施 Q DTM 0059 2011 IV 版本更替和修订记录表 时间 起草或修订 人 评审人修改内容 2009 12 11 庞然 幸勇 廖军 段雄 文 廖军 冯学勇 幸 勇 庞然 符冠 王述振 李毅杰 林艺 张有文 陈 伯勇 杨骥 初稿 2011 5 11 张璇 王凯 2 李诚 于喜 朝 彭强 张新发 刘江伟 梁斌 赵 晗 谢瑞莲 王凯 李毅杰 增加了第 7 章内容 完善了 编程规则和建 议 的内容 将其设置为一个章节 2011 5 26 张璇根据评审意见修改 Q DTM 0059 2011 1 大唐移动通信设备有限公司标准 Java 语言编程规范 1范围范围 本标准规定了 Java 编程规范的总则 Java 编程规范的规则及代码的文档格式 本标准适用于所有使用 Java 语言作为开发语言的项目 2规范性引用文件规范性引用文件 1 Java Coding Standard and Recommendation SUN 2 Writing Robust Java Code 3 How to Write Doc Comments for the Javadoc Tool SUN 4 The Java API Documentation Generator SUN 5 代码走读指导书 大唐移动代码走读项目 3定义 符号和缩略语定义 符号和缩略语 JDK Java Development Kit Eclipse 著名的跨平台的自由集成开发环境 IDE PMD 一个 Java 源码分析器 Checkstyle 提供了一个帮助 JAVA 开发人员遵守某些编码规范的工具 4编程规范总则编程规范总则 为了保持代码风格的一致乃至后续的可维护及可跟踪性 有时候必须减少部分灵活性及增加写注释 的时间来保证 实践证明在代码注释 文档上多投入时间 会在项目维护期得到丰厚的回报 没有规范的注释或者可读性很差的代码所构建的系统是没有必要运行的 即使运行了 项目也会 因维护性差而陷入困境 我们强调代码注释的重要性 一个好的注释应该包含三项 1 这段代码干了什么 WhatWhat 2 逻辑如何实现 HowHow 3 业务上为什么这样处理 或者流程为什么这样处理 WhyWhy 在我们写完代码的时候请检查一下自己写的文档注释是不是满足了 What how why 的要求 当然 解释问什么这样处理 是在必要时才添加 问 如何衡量一个函数代码质量的好坏 答 可以让程序阅读者在 30 秒之内能大致了解函数是干什么用的 问 如何保证代码的质量 答 1 程序员自觉遵守编程规范 2 定期互查以及自动化工具 包括 Eclipse 提供的及 PMD 或者 checkstyle 等外部自动化检查工 具 问 如何使用 Eclipse 进行高质量且高效的开发 答 1 Eclipse 提供了丰富的快捷键方式 比如 Ctrl Shift T Ctrol O Ctrl Shift L Ctrl Shift F 2 Eclipse 提供了 Code Style 的工具 比如 Code Templates Formatter Organize Imports 有这些功能都可以定制 为了保证代码风格的一致 应该统一使用公司定义的风格 公司已 Q DTM 0059 2011 2 经提供了一套 Eclipse 标准的开发环境 该开发环境已经内置了一些基本的规则 公司会定 期根据开发人员反馈的规则使用情况来调整和增加规则 Eclipse 提供了 Editor 的 Content Assist 的功能 同上 公司已经制定一套代码模板 一些常 用的代码将被列入模板 同时模板会根据实际中总结出的经验不断更新 所以 Eclipse 这套模板功能 能有效地减少程序员的劳动强度 5命名规则 命名规则 namingnaming conventionsconventions 类别类别规则规则样例样例 通用 规则 规则 5 1 采用全英文单词 大小写混合命名的方式 采用该领域的术语 尽量少用单词的缩写形式 如果一定要用 必须选 择通用的缩写方式 并且在本 Java 源代码中坚持使 用 避免使用相似或仅在大小写上有区别的名字 尽量避免太长的命名 一般以少于 15 个字符为宜 尽量避免使用下划线 模板变量名如果未使用 List ArrayList 等明显标示 统一在变量名后增加 s 如 List adjCells 或 List adjCellList 类 规则 5 2 第一个单词的首字母必须大写 其它单词的首字母也 要大写 如 PerfTaskClass 属性 变量 规则 5 3 第一个单词全部小写 以后单词的第一个字母大写 其余小写 对于数组类型的数值类型属性 应该采用单 词复数的方式命名 在最后一个单词加上 s 对于 Vector List Map Set 等集合数据类型属性 应该采 用单词后加上类型的方式命名 如 firstName int scores 1 2 3 List nameList new ArrayList 组件 变量 规则 5 4 与属性变量类似 但是采用将组件类型名作为后缀的 命名方法 如 cancelJButton 成员 方法 规则 5 5 方法名的第一个单词均小写 其它单词的首字母大 写 而且方法名中的第一个单词最好是动词形式 获取方法以 get 为前缀 设置方法以 set 为前缀 如 deleteTask save 如 getDN setName isEditable Q DTM 0059 2011 3 判断方法以 is 为前缀 当方法参数和类成员同名时 在方法参数前增加 a 进行区别如 public void int aCounter this counter aCounter 构造 方法 规则 5 6 构造方法必须具有与类名完全一致的名字 其大小写 也必须完全一致 常量 规则 5 7 以大写字母和下划线组成 以下划线作为区分语义各 部分的分割符 DEFAULT VALUE 文件 规则 5 8 文件名必须与包含有 public 关键字的类名或接口名完 全一致 即大小写也必须完全一致 并且在一个文件中 只能包含有一个 public 关键字的类或接口 文件名的后 缀必须是 java 接口 规则 5 9 接口名的第一个字母必须是大写的 I 其它部分 与类的命名规范一样 接口实现类名最后加 Impl 如 public interface IOmtApp 包 规则 5 10 包名全部用小写字母命名 包与子包之间或包与类之间用 加以区别 包名以 com datangmobile 开始 如 com datangmobile jbcl 6文件组织 文件组织 FileFile OrganizationOrganization 6 1定义文件的结构定义文件的结构 规则 6 1 1 所有的 Java java 文件必须遵守如下的样式规则 1 版权信息 版权信息必须放在 java 文件的开头 比如 Copyright c 2009 Datang Mobile Co Ltd All right reserved 其它不需要出现在 javadoc 的信息也可以包含在这里 Eclipse 中设置文件格式的方法 Q DTM 0059 2011 4 菜单拦中选中 Windows Preferences 在弹出框中进行如下的设置 2 package import package 行要在 import 行之前 与 import 之间空一行 import 中标准的 包名要在本地的包名之前 而且按照字母顺序排序 每个字母的 import 结束之后下面空一行 package om conference applet import java io import java util List import java util Observable import myPackage a import myPackage b 3 Class 类注释 类注释必须放在所有的 import 语句之后 紧靠在类定义之前 A panel with buttons and keyboard shortcuts to change the background color Q DTM 0059 2011 5 接下来是类定义 包含了 extends 和 implements 部分 public class ActionPanel extends JPanel implements ActionListener 4 类的属性 public protected 类型的属性必须使用文档型注释 以便于生成文档 javadoc private 定义的属性如果名字含义明确的话 可以没有注释 5 构造函数 构造函数用递增的方式列出 参数多的写在后面 6 类方法 public 的类方法必须使用文档型注释 以便于生成文档 javadoc 方法所带参数 也需给出注释 Returns the smaller of two int val ues That is the result the argument closer to the value of Integer MIN VALUE If the arguments have the same value the result is that same value param a an argument param b another argument return the smaller of a and b see java lang Long MIN VALUE public static int min int a int b return a datangmobile department group 目录结构存放 6 3其它其它 规则 6 3 1 所有的文件和类都必须包含具有版权信息的标准注释头 规则 6 3 2 类的公有类型 保护类型和私有类型部分在类体中以如下次序说明 先说明公有类 型部分 然后说明保护类型部分 最后说明私有类型部分 这样便于用户使用公有类型部分 规则 6 3 3 业务类文件的长度不超过 1000 行 公共类的长度不超过 2000 行 规则 6 3 4 static 变量声明区和方法定义区分开 static 的变量在变量区的最前面 其后是 static 块 static 变量区后为其他的成员变量 see getUIClassID see readObject public static final int AUTO RESIZE OFF 0 private static final String uiClassID TableUI Do not adjust column widths automatically use a scrollbar public static final int AUTO RESIZE OFF 0 Q DTM 0059 2011 6 static do something The TableModel of the table protected TableModel dataModel The TableColumnModel of the table protected TableColumnModel columnModel private SizeSequence rowModel private boolean dragEnabled private boolean surrendersFocusOnKeystroke 方法定义放在变量定义区之后 建议按照 public protected private 方法的顺序来放置 7程序板式程序板式 版式虽然不会影响程序的功能 但会影响可读性 程序的版式追求清晰 美观 是程序风格的重 要构成因素 如果使用 JBuilder 开发 建议使用 Java Formatting 中的 Java Standard 方式 和下文 描述的方式一致 7 1空行空行 空行起着分隔程序段落的作用 空行得体 不过多也不过少 将使程序的布局更加清晰 空行不 会浪费内存 建议 7 1 1 在每个类声明之后 每个方法定义结束之后都要加空行 参见示例 4 1 a 建议 7 1 2 在一个函数体内 逻揖上密切相关的语句之间不加空行 其它地方应加空行分隔 参见示例 7 1 b 示例示例 7 1 a 方法之间的空行方法之间的空行 空行 void method1 空行 void method2 空行 void method3 示例示例 7 1 b 方法内部的空行方法内部的空行 空行 while condition statement1 空行 if condition statement2 else statement3 Q DTM 0059 2011 7 空行 statement4 7 2代码行代码行 规则 7 2 1 if for while do 等控制语句自占一行 执行语句不得紧跟其后 不 论执行语句有多少都要加 这样可以防止书写错误 示例 7 2 a 为风格良好的代码行 示例 7 2 b 为风格不良的代码行 int width 宽度 int height 高度 int depth 深度 x a b y c d z e f if width height dosomething for initialization condition update dosomething 示例示例 7 2 a 风格良好的代码行风格良好的代码行 int width height depth 宽度高度深度 X a b y c d z e f if width i 10 i 和 if a b i 10 i 良好的风格 for i 0 i 10 i 不良的风格 for i 0 i 10 i 过多的空格 x a b a b 良好的风格 x a b a b 不好的风格 array 5 0 不要写成 array 5 0 a method1 不要写成 a method1 示例示例 7 3 代码行内的空格代码行内的空格 7 4对齐对齐 规则 7 4 1 标志代码块的 应和所属代码段位于同一行 应独占一行并且位 于代码段开头的同一列 同时与引用它们的语句左对齐 如 for int i 0 i very longer variable12 for very longer initialization very longer condition very longer update dosomething 示例示例 4 5 长行的拆分长行的拆分 规则 7 5 3 保持单个方法长度在 200 行以内 确保方法功能单一 简洁 7 6注释注释 JAVA 中有三种表示注释的方法 注释类型注释类型 使用范围使用范围 文档型 对于类 接口 方法和非private属性 必须使用该 种注释 块注释 禁止使用 单行注释 内部注释 1 单行注释 用来注释从 开始一直到该行结束之间的内容 一般用在成 员函数内部对业务逻辑 代码片断和临时变量声明进行说明 2 和 文档型注释 其界定的部分可以用 javadoc 生成 HTML 形式的 外部注释文档 一般用于在接口 类 成员函数和字段声明之前进行说明 使用 以 开始的注释 可以很容易地产生专业化的文档 有助于帮助编程人员理解代 码 以及保持源代码和文档注释的一致 因此在 Java 源代码中推荐采用这种注释 方式 由于文档型注释是用于生成 HTML 形式的文档 因此其中的文字格式需使用 HTML 的相关语法 3 和 块注释 由于该注释类型经常和文档型注释混淆 而且 eclipse Q DTM 0059 2011 11 默认会格式化块注释 同时块注释在 eclipse 里有很好的替代品 Ctrl 所以 原则上我们禁止使用块注释 javadoc 工具从以下各项中提取信息 包 公开类和接口 公开和受保护的方法 公开和受保护的字段 对于添加注释 有如下一些规定和建议 规则 7 6 1 每条注释都放在它所描述的部件上面 紧靠着 注释以 开始 以 结束 规则 7 6 2 每条 文档注释在标签之后都包含有自由形式的文本 标签以 开始 例如 author 或 param 规则 7 6 3 自由形式文本的第一个句子应当为一个概要语句 javadoc 工具会自动地 提取这些句子以产生概要页 规则 7 6 4 如果文档中含有对其它文件的链接 比如图像 那么应该把这些文件放 在名为 doc files 的子目录中 javadoc 工具将从源目录中拷贝这些目录 以及目录 下的文件到文档目录下 规则 7 6 5 在每个方法定义前加一个恰当的方法说明 描述该方法的功能 参数 返回值 异常 注意事项和修改记录等 规则 7 6 6 包注释 要产生包注释 需要在每个包目录中增加一个名为 package html 的文件 所有在标签 之间的文本都会被提取 包注释 应说明包的基本原理和包中的类 要有一个包中的类和接口的列表 并用简短的文字 说明 规则 7 6 7 概要注释 将一个名为 overview html 的文件放在包含所有源文件的父 目录下 所有在标签 之间的文本都会被提取 规则 7 6 8 author authorname 产生一个 作者 条目 一般在类 接口定义之 前的文档注释里使用 规则 7 6 9 version text 产生一个 版本 条目 一般在类 接口定义之前的文 Q DTM 0059 2011 12 档注释里使用 规则 7 6 10 param variable description 用于方法注释 用于说明传递给该成 员方法的参数 包括其类型和它的使用 规则 7 6 11 return description 用于方法注释 用于说明本成员方法的返回值 类型 如果可能 适当的描述其可能的返回值 规则 7 6 12 throws class description 用于方法注释 用于本成员方法可能抛 出的异常 规则 7 6 13 deprecated text 一般在类 成员方法定义之前的文档注释里使用 用于声明一个类或者一个成员方法被废弃 不再使用 规则 7 6 14 see 一般在类 接口 成员方法 域定义之前的文档注释里使用 用 于建立一个超链接到 javadoc 文档的其它相关部分 或链接到外部的文档 建议 7 6 1 在自由形式的文本中 可以使用 HTML 指示符 例如用于强调的 甚至用于包含图像的 但是 不能使 用标题或者规则 因为它们会与文档的格式发生冲突 建议 7 6 2 边写代码边注释 修改代码同时修改相应的注释 以保证注释与代码的 一致性 不再有用的注释要删除 建议 7 6 3 尽量避免在注释中使用缩写 特别是不常用缩写 建议 7 6 4 当代码比较长 特别是有多重嵌套时 应当在一些段落的结束处加注释 便于阅读 8编程规则和建议编程规则和建议 8 1表达式表达式 规则 8 1 1 在表达式中用括号使子表达式的运算顺序清晰 必须确保表达式中的操 作数的运算顺序不会对表达式的值造成影响 尤其在可能有副作用的子表达式中 必 须保证有准确定义的运算顺序 反例 缺少括号 导致可读性很差 甚至产生歧义 result a b c d 2 if charEncoding equals CHARACTER ENCODING 反例 if charEncoding equals GB2312 建议 8 1 1 不要在逻辑表达式中使用按位操作符 idx2 max min left 1 idx2 right idx3 if right limit 建议 8 1 3 在 if for 和 while 语句中要使用布尔型控制表达式 如果该表达式不 是逻辑表达式 就用显式验证 建议 8 1 4 避免逻辑表达式的结果为恒真或恒假 这样的判断往往是毫无意义的 有时也是潜在隐藏的 bug 不能到达程序的某些部分 8 2声明和定义声明和定义 建议 8 2 1 将声明和定义放在方法的开始处 这样便于找到某一个特定变量的定义 建议 8 2 2 在变量的可见空间内不要定义重名变量 建议 8 2 3 在最小可能的范围内声明变量 8 3整数数据类型整数数据类型及操作及操作 规则 8 3 1 移位运算时 对前面的位填充符号位 对前面的位填充 0 规则 8 3 2 移位运算符右边的变元要被进行模 32 运算 如果左边的变元是 long 类 型的 右边的变元要进行模 64 运算 例如 1 35 的值与 1 3 的值是同等的 都等于 8 Q DTM 0059 2011 15 建议 8 3 1 不要用移位操作代替乘 除 2 的幂的操作 建议 8 3 2 不要用 int nx int x 规则 8 7 2 不能在布尔值和任何数值类型间造型 8 8常量常量 规则 8 8 1 在 Java 中 使用关键字 final 来表示常量 规则 8 8 2 使用关键字 static final 设定类常量 类常量在某个类的多个方法中可 用 如果类常量声明为 public 那么其他类中的方法也可以使用这个常量 8 9控制控制流程流程 规则 8 9 1 Java 中没有 goto 规则 8 9 2 在 Java 中 不允许在两个嵌套的块内声明相同名字的变量 例如 下面的代码是错误的 它不会被编译 public static void main String args int n int k int n error can t redefine n in inner block 建议 8 9 1 使用 switch 语句的建议 条件不是彼此互斥时 不要用 switch 语句 每个 case 标签要以 break 语句结束 Q DTM 0059 2011 17 在 switch 语句的末尾写一条非空的 default 语句 一般情况下 case 标 签不能包括所有可能值 default 标签代表所有 case 标签未包括的值 如果 switch 表达式的所有值都被 case 标签包括了 可以用 default 语句检查程 序的错误行为 不能在 switch 和第一个 case 之间放置语句 在每个 case 语句后 书写相应的注释 建议 8 9 2 else if 语句的写法 else if 语句应该写成条件从上向下读 遇到第一个能够满足的条件 就执行所 对应的语句部分 而随后的结构都跳过去 最后一个 else 处理默认情况 即没有 选中其他部分时的情况 或者给出一个错误信息 在书写的时候所有的 else 垂直 对齐 而不是让每个 else 与对应的 if 对齐 这样的写法能强调所有的判断都是 顺序进行的 反例 if condition 1 if condition 1 1 if condition 1 1 1 statement 1 1 1 else statement 1 1 0 else statement 1 0 else statement 0 范例 if condition 1 statement 1 else if condition 2 statement 2 Q DTM 0059 2011 18 else if condition n statement n else default statement 建议 8 9 3 循环语句的写法 循环语句尽量用 for 语句编写 并尽可能使用 for i 0 i n i 的格式 保证循环变量的增量操作写在 for 语句括号中第二个分号后 建议 8 9 4 在流程控制原语 if else while for 和 do 的后边应该跟一个程序块 即 即使该程序块是一个空程序块 8 10 垃圾收集垃圾收集 规则 8 10 1 必须在使用完对象的实例后进行清场工作 例如常用的文件流 数据库 连接 锁 会话等 建议 8 10 1 有策略逻辑的垃圾资源释放 建议都捕获异常 若有异常处理必须放 在 finally 执行体内释放资源 回收垃圾 如 FileOutputStream fos new FileOutputStream projectFile Project save fos IDE Project File fos close 8 11 错误处理错误处理 规则 8 11 1 如果一个方法可能抛出多个异常 那么则必须在方法头部中列出所有的 异常 建议 8 11 1 提醒应该先捕获自定义异常 最后捕获标准异常 try catch CustomException e Q DTM 0059 2011 19 catch Exception e 规则 8 11 2 禁止在 catch 中对于异常的 printStackTrace 的使用 建议 8 11 2 尽量避免使用 System exit 8 12 断言断言 断言函数可以用来明确地表达先决条件和后置条件 也可以用来记录和调试 断言使 用逻辑表达式 布尔型 作为参数 能够在程序中的任意位置调用 如果表达式的值为假 断言函数会使程序非正常终止 如果表达式的值为真 调用断言函数不会产生任何影响 建议 8 12 1 在下列情况中 应调用错误处理器 而尽量不要使用断言 8 13 类类 建议 8 13 1 构造器中应初始化必要的属性 其他属性可有选择的通过设置器 set 方法 设置 构造器中根据业务需要执行必要的初始策略 规则 8 13 2 构造器必须和 new 运算符结合使用 建议 8 13 2 在类的构造器中不要有复杂的操作 一定要保证构造器中的操作不会出 错 这是因为 构造器本身不能返回错误 建议 8 13 3 写 clone 方法时 需要写 super clone 确保首先把父类成员复制 8 14 通用规则和建议通用规则和建议 规则 8 14 1 编译时将告警级别设置为最高并消除所有警告 8 15 LOG 打印格式打印格式 建议 8 15 1 在业务代码中禁止使用 System out print 有控制台上的特殊提醒 比如 服务器启动成功 等 尽量用 LOG 打印 避免使用 System out print 建议 8 15 2 LOG 的打印格式如下 应该包含日期 包名 类名 方法名 其中打印 的内容应以英文表示 不能含有汉字 例如 日期 包名 类名 方法名 提示信息 异常信息 Q DTM 0059 2011 20 9代码文档格式代码文档格式 9 1文档内容的基本要求文档内容的基本要求 注意 下列表格中标识为 必要时 的标签是指在有必要时一定要加入 而不是可加 可不加 所谓 必要时 是指在上下文有相关引用 或者内容相关或者相似的 主要是为 了使程序阅读者快速理解代码含义及渊源 同时使整个代码形成一个有机的整体 具体 必要时 的语境请理解标签的 目的 所描述的含义 JDK 有良好的范本供参考 9 2属性相关的文档标签属性相关的文档标签 编程人员必须理解下列 JavaDoc 标签的含义 并在必要时应该在每个属性注释里体现 出来 标签标签 适用范围适用范围 目的目的 values 属性 描述属性可能被赋予的值 see ClassName 必要时 Classes Interfaces 成 员函数 Fields 在文档里生成指向指定类的超链接 最好使 用类的全名 see ClassName member functionName 必要时 Classes Interfaces 成 员函数 Fields 在文档里生成指向指定方法的超链接 最好 使用类的全名 9 3类相关的文档标签类相关的文档标签 编程人员必须理解下列 JavaDoc 标签的含义 并在必要时应该在每个类注释里体现出 来 标签标签 适用范围适用范围 目的目的 author name Interfaces Classes Interfaces 指示代码的作者 每个作者都应该使用独立 的标签 deprecated 必要时 Interfaces Classes 成员 函数 表示该类或者接口的API已经废弃 不应该继 续使用 since Interfaces Classes 成员 函数 表示该项已经存在的历史 比如 since JDK 1 1 see ClassName 必要时 Classes Interfaces 成员函数 属 性 在文档里生成指向指定类的超链接 最好使 用类的全名 see ClassName member functionName 必要时 Classes Interfaces 成员函数 属 性 在文档里生成指向指定方法的超链接 最好 使用类的全名 Q DTM 0059 2011 21 version text Classes Interfaces 用于指示当前代码的版本 9 4函数应该包含的文档标签函数应该包含的文档标签 编程人员必须理解下列 JavaDoc 标签的含义 并在必要时应该在每个函数注释里体现 出来 标签标签 适用范围适用范围 目的目的 deprecated 必要时 Interfaces Classes 成员 函数 表示该类或者接口的API已经废弃 不应该继 续使用 param name description 必要时 成员函数 描述函数的参数 包含它的类型及用法 参 数的取值范围 每个参数都应该使用独立 的标签 throws exception was the original tag name description 必要时 成员函数 描述成员函数抛出的异常 每个异常都应该 使用独立的标签 而且要使用类的全名 return description 成员函数 描述函数的返回值 如果有 应该指明返 回值的类型及用法 特别要包含返回值的意 义及取值范围 see ClassName 必要时 Classes Interfaces 成 员函数 属性 在文档里生成指向指定类的超链接 最好使 用类的全名 see ClassName member functionName 必要时 Classes Interfaces 成 员函数 属性 在文档里生成指向指定方法的超链接 最好 使用类的全名 9 5其它注释标签其它注释标签 建议程序员添加下列标签来说明函数或者类 标签标签 适用范围适用范围 目的目的 bug description Classes 成员 函数 描述类或者成员函数已知的bug 每个bug都 应该使用独立的标签 concurrency description Classes 成员 函数 属性 描述类 函数 属性的并发处理策略 方法 copyright year description Classes 描述类的copyright Year是指哪一年获得 的版权 及描述获得版权的个人姓名或者组 织名称 example description Classes 成员 函数 Fields 提供一个或者多个示例以说明指定类 成员 函数 属性的用法 有利于开发者快速理解 你的代码 fyi description Classes Interfaces 成 员函数 属性 提供你已经做出的决定或者你认为有益的事 情的信息 Q DTM 0059 2011 22 history description Classes 成员 函数 描述类 方法被修改的历史 每个重要修改 都应该包含 谁修改的 什么时候修改的 做了什么 为什么要做 提供变更需求或者 用户需求的出处 modifies no 成员函数 表明成员函数没有修改对象 modifies yes description 成员函数 表明成员函数修改了对象 并告诉如何修改 的 postcondition description 成员函数 描述方法执行后应该成立的条件 每个条件 都应该使用独立的标签 precondition description 成员函数 描述方法执行前应该成立的条件 每个条件都应该使用独立的标签 reference description Classes Interfaces 成 员函数 属性 描述相关业务逻辑或者相关代码的文档的出 处 9 6包和综述注释包和综述注释 前面的都是针对某一个类 函数等的注释 可以直接放在 JAVA 源文件中 然而为了生 成一个包的注释 必须在每个包的目录下放置一个名为 package html 的文件来对包进行描 述 标签 之间的文字都会被 javadoc 自动提取出来 也可以为所有源文件提供一个综述注释 写入名为 overview html 文件中 将其放在 所有源文件所在的父目录下面 标签 之间的文字也都会被 javadoc 自 动提取出来 做成文档的 Overview 9 7常用注释链接标签常用注释链接标签 JavaDoc 可以兼容 HTML 的标签 HTML 的标签的使用可以提高 JavaDoc 所生成文档的可 读性 JavaDoc 也自定义了一些标签 有关这些标签的详细描述请查阅参考文档 JavaDoc 常用标签举例 标签标签 用途用途 举例举例 literal text 等价于 code text 用于表示包含部 分不做HTML解析 多用于代码或者 特殊字符的处理 code AC 将不会对解释成HTML的黑体格式 用于分段 标准 的HTML标签 见下面的例子 用于演示代码见下面的例子 以下是JDK的Integer的toString int i int radix 方法注释 Returns a string representation of the first argument in the radix specified by the second argument If the radix is smaller than Character MIN RADIX Q DTM 0059 2011 23 or larger than Character MAX RADIX then the radix 10 is used instead If the first argument is negative the first element of the result is the ASCII minus character u002D If the first argument is not negative no sign character appears in the result The remaining characters of the result represent the magnitude of the first argument If the magnitude is zero it is represented by a single zero character 0 u0030 otherwise the first character of the representation of the magnitude will not be the zero character The following ASCII characters are used as digits 0123456789abcdefghijklmnopqrstuvwxyz These are u0030 through u0039 and u0061 through u007A If radix is N then the first N of these characters are used as radix N digits in the order shown Thus the digits for hexadecimal