Java注释

Java注释简介

在Java中说起注释,我们需要先知道什么是元metadata,这个单词我们国内一般翻译为元数据,所谓元数据,就是数据的数据。也就是说,元数据存在的意义,就是为了描述数据。有了元数据的概念以后,我们就可以把注释称作Java代码的元数据。

作用

程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本 , 并且几乎没有任何一个软件,在其整个生命周期中,均由最初的开发人员来维护。好的注释规范可以改善软件的可读性,可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯,甚至锻炼出更加严谨的思维能力。 

类型

1、单行(single-line)--短注释://……   

单独行注释:在代码中单起一行注释, 注释前最好有一行空行,并与其后的代码具有一样的缩进层级。如果单行无法完成,则应采用块注释。
注释格式:/* 注释内容 */
行头注释:在代码行的开头进行注释。主要为了使该行代码失去意义。
注释格式:// 注释内容
行尾注释:尾端(trailing)--极短的注释,在代码行的行尾进行注释。一般与代码行后空8(至少4)个格,所有注释必须对齐。
注释格式:代码 + 8(至少4)个空格 + // 注释内容

2、块(block)--块注释:/*……*/

注释若干行,通常用于提供文件、方法、数据结构等的意义与用途的说明,或者算法的描述。一般位于一个文件或者一个方法的前面,起到引导的作用,也可以根据需要放在合适的位置。这种域注释不会出现在HTML报告中。注释格式通常写成:
/*
  * 注释内容

  */ 

3、文档注释:/**……*/

注释若干行,并写入javadoc文档。每个文档注释都会被置于注释定界符
/**......*/之中,注释文档将用来生成HTML格式的代码报告,所以注释文
档必须书写在类、域、构造函数、方法,以及字段(field)定义之前。注释文档由两部分组成——描述、块标记。
     <1>文档和文档注释的格式化
               因为生成的文档是HTML 格式,所以格式化文档就是在注释间添加相应的HTML 标识
               注意:文档注释只说明紧接其后的类、属性或者方法。
      <2>注释的三部分
               eg:
                /**
       * show 方法的简述.
           * <p>show 方法的详细说明第一行<br>
           * show 方法的详细说明第二行
           * @param b true 表示显示,false 表示隐藏
           * @return 没有返回值
           */ public void show(boolean b) {
              frame.show(b);
          }
                第一部分是简述。文档中,对于属性和方法都是先有一个列表,然后才在后面一个一个的详细的说明。列表中属性名或者方法名后面那段说明就是简述。
                第二部分是详细说明部分。该部分对属性或者方法进行详细的说明,在格式上没有什么特殊的要求,可以包含若干个点号。
                第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。

标签语法

javadoc 标记是插入文档注释中的特殊标记,它们用于标识代码中的特殊引用。javadoc 标记由“@”及其后所跟的标记类型和专用注释引用组成。记住了,三个部分——@、标记类型、专用注释引用。
@author    对类的说明 标明开发该类模块的作者
@version   对类的说明 标明该类模块的版本
@see      对类、属性、方法的说明 参考转向,也就是相关主题
@param    对方法的说明 对方法中某参数的说明
@return    对方法的说明 对方法返回值的说明
@exception  对方法的说明 对方法可能抛出的异常进行说明 

规范

1、 注释形式统一 
在整个应用程序中,使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同,按照他们的规范写代码,不要试图在既成的规范系统中引入新的规范。 
2、 注释的简洁 
内容要简单、明了、含义准确,防止注释的多义性,错误的注释不但无益反而有害。 
3、 注释的一致性 
在写代码之前或者边写代码边写注释,因为以后很可能没有时间来这样做。另外,如果有机会复查已编写的代码,在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建,解释性注释在开发过程中创建,提示性注释在代码完成之后创建。修改代码的同时修改相应的注释,以保证代码与注释的同步。 
4、 注释的位置 
保证注释与其描述的代码相邻,即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置,不可放在下方。避免在代码行的末尾添加注释;行尾注释使代码更难阅读。不过在批注变量声明时,行尾注释是合适的;在这种情况下,将所有行尾注释要对齐。 
5、 注释的数量 
注释必不可少,但也不应过多,在实际的代码规范中,要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”,而不是文档,程序中的注释不可喧宾夺主,注释太多了会让人眼花缭乱,注释的花样要少。不要被动的为写注释而写注释。 
6、删除无用注释 
在代码交付或部署发布之前,必须删掉临时的或无关的注释,以避免在日后的维护工作中产生混乱。 
7、 复杂的注释 
如果需要用注释来解释复杂的代码,请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码,而应该重写它。尽管一般不应该为了使代码更简单便于使用而牺牲性能,但必须保持性能和可维护性之间的平衡。 
8、 多余的注释 
描述程序功能和程序各组成部分相互关系的高级注释是最有用的,而逐行解释程序如何工作的低级注释则不利于读、写和修改,是不必要的,也是难以维护的。避免每行代码都使用注释。如果代码本来就是清楚、一目了然的则不加注释,避免多余的或不适当的注释出现。 
9、必加的注释 
典型算法必须有注释。在代码不明晰或不可移植处必须有注释。在代码修改处加上修改标识的注释。在循环和逻辑分支组成的代码中添加注释。为了防止问题反复出现,对错误修复和解决方法的代码使用注释,尤其是在团队环境中。 
10、注释在编译代码时会被忽略,不编译到最后的可执行文件中,所以注释不 会增加可执行文件的大小。 

常用模板

类型(Types)注释标签(类的注释):

/** 
* @ClassName: ${type_name} 
* @Description: ${todo} 
* @author A18ccms a18ccms_gmail_com 
* @date ${date} ${time} 

* ${tags} 
*/

字段(Fields)注释标签:

/** 
* @Fields ${field} : ${todo} 
*/ 
构造函数注释标签:

/** 
* <p>Title: </p> 
* <p>Description: </p> 
* ${tags} 
*/

方法(Constructor & Methods)注释标签:

/** 
* @Title: ${enclosing_method} 
* @Description: ${todo} 
* @param ${tags}    设定文件 
* @return ${return_type}    返回类型 
* @throws 
*/

例子

类/接口注释

/**
 * The <code>String</code> class represents character strings. All
 * string literals in Java programs, such as <code>"abc"</code>, are
 * implemented as instances of this class.
 * (其他描述)
 * @author Lee Boynton
 * @author Arthur van Hoff
 * @author Martin Buchholz
 * @author Ulf Zibis
 * @see java.lang.Object#toString()
 * @see java.lang.StringBuffer
 * @see java.lang.StringBuilder
 * @see java.nio.charset.Charset
 * @since JDK1.0
 */ public final class String implements java.io.Serializable, Comparable<String>, CharSequence { ...
}

构造器注释

/**
     * Initializes a newly created {@code String} object so that it represents
     * the same sequence of characters as the argument; in other words, the * newly created string is a copy of the argument string. Unless an
     * explicit copy of {@code original} is needed, use of this constructor is * unnecessary since Strings are immutable.
     *
     * @param  original
     *         A {@code String}
     */
    public String(String original) {
        this.value = original.value;
        this.hash = original.hash;
    }

方法注释

/**
     * Returns <tt>true</tt> if, and only if, {@link #length()} is <tt>0</tt>.
     *
     * @return <tt>true</tt> if {@link #length()} is <tt>0</tt>, otherwise
     * <tt>false</tt>
     *
     * @since 1.6
     */ public boolean isEmpty() { return value.length == 0;
    }

字段/属性注释

/** The value is used for character storage. */ private final char value[]; /** Cache the hash code for the string */ private int hash; // Default to 0 /** use serialVersionUID from JDK 1.0.2 for interoperability */ private static final long serialVersionUID = -6849794470754667710L; /**
     * Class String is special cased within the Serialization Stream Protocol.
     *
     * A String instance is written initially into an ObjectOutputStream in the
     * following format:
     * <pre>
     *      <code>TC_STRING</code> (utf String)
     * </pre>
     * The String is written by method <code>DataOutput.writeUTF</code>.
     * A new handle is generated to  refer to all future references to the
     * string instance within the stream.
     */ private static final ObjectStreamField[] serialPersistentFields = new ObjectStreamField[0];




精彩推荐

Java注释

点击 6919

Java注释规范

点击 6411