一、注释及简介
1、鄙人写的一些代码中,虽说有注释,但都是一些不符合规则的注释,即便拿出来查阅,也要花很一些时间才能搞懂程序的流程。为了良好的编程风格,我特意学习了java的文档注释,也分享给大家,良好的编程风格确实很重要,不可忽略···
2、说一个简单的问题,什么是注释呢?注释就是让编码器不编译(不执行),在代码的编写过程中我们需要对一些程序进行注释,除了自己方便阅读,更为别人更好理解自己的程序,所以我们需要进行一些注释,可以是编程思路或者是程序的作用,总而言之就是方便自己他人更好的阅读。
二、分类及原则
从用途上分,注释可以分为序言性注释和功能性注释。
1、序言性注释:通称位于程序或者模块的开始部分。它给出了程序或模块的整体说明,这种描述不包括程序的执行过程细节。
2、功能性注释:一般嵌入在源程序体之中。其主要描述某个语句或程序段做什么,执行该语句或程序段会怎样,不是解释怎么做。只有复杂的执行细节才需要嵌入注释,描述其实现方法。
三、注释的基本原则
1、注释应该增加代码的清晰度。
2、避免使用装饰性内容。
3、保持注释的简洁。
4、注释信息不仅要包括代码的功能,还应给出原因。
5、不要为注释而注释。
6、除变量定义等较短语句的注释可用行尾注释外,其他注释应当避免使用行尾注释。
四、注释格式
代码注释格式:
// 注释一行
/* ...... */ 注释若干行
/** ...... */ 注释若干行,并写入 javadoc 文档
TODO注释:
@Override
public void submitOnly() {
// TODO Auto-generated method stub
}
如果代码中有该标识,说明在标识处有功能代码待编写,待实现的功能在说明中会简略说明。 文档注释: 文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件),而是读取每一行后,删掉前导的 * 号及 * 号以前的空格,再输入到文档的。
五、注释标记
javadoc 标记是插入文档注释中的特殊标记,它们用于标识代码中的特殊引用。javadoc 标记由“@”及其后所跟的标记类型和专用注释引用组成。记住了,三个部分——@、标记类型、专用注释引用。虽然 @ 和 标记类型之间有时可以用空格符分隔,但是推荐将它们紧挨着写,以减少出错机会。
javadoc 标记有如下一些:
@author 标明开发该类模块的作者 (对类的说明)
@version 标明该类模块的版本 (对类的说明)
@see 参考转向,也就是相关主题 (对类、方法、属性的说明)
@param 对方法中某参数的说明 (对方法的说明)
@return 对方法返回值的说明 (对方法的说明)
@deprecated 引起不推荐使用的警告(对方法的说明)
@since 最早使用该方法/类/接口的JDK版本(对类的说明)
@exception 对方法可能抛出的异常进行说明 (对方法的说明)
其中,@author 可以多次使用,以指明多个作者,生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次,只有第一次有效
六、重点标记详解
1、@see 的三种句法:
@see 类名
@see #方法名或属性名
@see 类名#方法名或属性名
2、使用 @author、@version 说明类
@author 作者名
@version 版本号
3、使用 @param、@return 和 @exception 说明方法
这三个标记都是只用于方法的。@param 描述方法的参数,@return 描述方法的返回值,@exception 描述方法可能抛出的异常。它们的句法如下:
@param 参数名 参数说明
@return 返回值说明
@exception 异常类名 说明
每一个 @param 只能描述方法的一个参数,所以,如果方法需要多个参数,就需要多次使用 @param 来描述。
七、类注释
1.类注释
/**
* 类 {类名称}
{此类功能描述}
* @author {作者}
* @version {版本,常用时间代替}
* @see java.lang.Class
* @since JDK{jdk版本} 或者编辑日期
*/
public class Object {}
/** The value is used for character storage. */
private char value[];
注释结构:
/** {此值是用来存储/记录什么的}*/
八、方法注释
使用 @param、@return 和 @exception 说明方法
方法注释采用 /** … */,描述部分注明方法的功能,块标记部分注明方法的参数,返回值,异常等信息
这三个标记都是只用于方法的。@param 描述方法的参数,@return 描述方法的返回值,@exception 描述方法可能抛出的异常。它们的句法如下:
@param 参数名 参数说明
@return 返回值说明
@exception 异常类名 说明
注释结构:
/**
* {方法的功能/动作描述}
* @param {引入参数名} {引入参数说明}
* @return {返回参数名} {返回参数说明}
* @exception {说明在某情况下,将发生什么异常}
*/
public String substring(int beginIndex)
{
return substring(beginIndex, count);
}
import java.lang.*;
/** commnet for class */
public class Test { ...... }
上例中的两处注释就是分别对类、属性和方法的文档注释。它们生成的文档分别是说明紧接其后的类、属性、方法的。“紧接”二字尤其重要,如果忽略了这一点,就很可能造成生成的文档错误
九、文档注释
/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示,false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}
第一部分是简述,列表中属性名或者方法名后面那段说明就是简述。简述部分写在一段文档注释的最前面,第一个点号 (.) 之前 (包括点号)。换句话说,就是用第一个点号分隔文档注释,之前是简述,之后是第二部分和第三部分。如上例中的 “* show 方法的简述.”。
有时,即使正确地以一个点号作为分隔,javadoc 仍然会出错,把点号后面的部分也做为了第一部分。为了解决这个问题,我们可以使用一个 <p> 标志将第二分部分分开,如上例的“* <p>show 方法的详细说明第一行 ....”。
第二部分是详细说明部分。该部分对属性或者方法进行详细的说明,在格式上没有什么特殊的要求,可以包含若干个点号。
第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。第三部分在上例中相应的代码是:
* @param b true 表示显示,false 表示隐藏
* @return 没有返回值
除了 @param 和 @return 之外,还有其它的一些特殊标记,分别用于对类、属性和方法的说明。
十、参考总结
关于注释的更多详情请参考
在sun主页上有java文档注释的编写格式
How to Write Doc Comments for the Javadoc Tool
http://java.sun.com/j2se/javadoc/writingdoccomments/
欢迎大家指正和沟通,谢谢大家!