Java编程基础--注释【知识体系构建系列】

本文只是粗浅地整理注释的相关知识点，保证够用，但未曾深挖，如有疑问或者建议，欢迎指出。

注释的作用：

注释用来说明某段代码的作用，或者说明某个类的用途，每个方法的功能，以及该方法的参数和返回值的数据类型及意义等。
另一方面：正如代码是写个人看的，丑陋的代码和过多的注释也不是什么好事，把握分寸也很重要

注释写法：

//单行注释
/* ..多行注释.... */  
/**.... 文档注释……*/

代码示例：

package com.leo.java.comment;
/**
 * 这是文档注释
 * @author xuexiaolei
 * @version 2018年01月11日
 */
public class Test {
    public static void main(String[] args) {
        //这是单行注释
        System.out.println("这是单行注释……");
        /*
        * 这是多行注释
        */
        System.out.println("这是多行注释……");
    }
}

IDE操作提示：
通用的Intellj/Eclipse快捷键如下：Ctrl+/是单行注释 Ctrl+Shift+/ 是多行注释
单行注释和多行注释是同一种颜色提醒，文档注释会高亮提醒。

注释通用规范：

• 必要的注释还是必须要有的，比如说JavaBean中的字段意义，就应该有相关的注释。
• 不要写一些的无用注释，比如给JavaBen的每个getter/setter方法作注释。
• 不要保留任何一行被注释掉的代码，现在代码一般都有版本工具git/svn做管理，所以根本不用担心代码会丢掉。
• 漂亮的通用的代码本身就是一种注释。
• 一般来说，公司都有通用的IDE注释模板，使用即可。如果没有可以参考来做成自己的模板：JAVA代码注释规范

文档注释详解

文档注释是可以被 javadoc 工具自动生成文档的方法的。

文档注释分为两部分：描述部分和标记部分

/**
* 描述部分(description) 
*
* 标记部分(block tags)
*/

Collection接口的注释示例

/**
* The root interface in the <i>collection hierarchy</i>. A collection
* represents a group of objects, known as its <i>elements</i>. Some
* collections allow duplicate elements and others do not. Some are ordered
* and others unordered. The JDK does not provide any <i>direct</i>
* implementations of this interface: it provides implementations of more
* specific subinterfaces like <tt>Set</tt> and <tt>List</tt>. This interface
* is typically used to pass collections around and manipulate them where
* maximum generality is desired.
*
* <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
* duplicate elements) should implement this interface directly.
*
* <p>All general-purpose <tt>Collection</tt> implementation classes (which
* typically implement <tt>Collection</tt> indirectly through one of its
* subinterfaces) should provide two "standard" constructors: a void (no
* arguments) constructor, which creates an empty collection, and a
* constructor with a single argument of type <tt>Collection</tt>, which
* creates a new collection with the same elements as its argument. In
* effect, the latter constructor allows the user to copy any collection,
* producing an equivalent collection of the desired implementation type.
* There is no way to enforce this convention (as interfaces cannot contain
* constructors) but all of the general-purpose <tt>Collection</tt>
* implementations in the Java platform libraries comply.
*
* <p>The "destructive" methods contained in this interface, that is, the
* methods that modify the collection on which they operate, are specified to
* throw <tt>UnsupportedOperationException</tt> if this collection does not
* support the operation. If this is the case, these methods may, but are not
* required to, throw an <tt>UnsupportedOperationException</tt> if the
* invocation would have no effect on the collection. For example, invoking
* the {@link #addAll(Collection)} method on an unmodifiable collection may,
* but is not required to, throw the exception if the collection to be added
* is empty.
*
* <p><a name="optional-restrictions">
* Some collection implementations have restrictions on the elements that
* they may contain.</a> For example, some implementations prohibit null elements,
* and some have restrictions on the types of their elements. Attempting to
* add an ineligible element throws an unchecked exception, typically
* <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting
* to query the presence of an ineligible element may throw an exception,
* or it may simply return false; some implementations will exhibit the former
* behavior and some will exhibit the latter. More generally, attempting an
* operation on an ineligible element whose completion would not result in
* the insertion of an ineligible element into the collection may throw an
* exception or it may succeed, at the option of the implementation.
* Such exceptions are marked as "optional" in the specification for this
* interface.
*
* <p>It is up to each collection to determine its own synchronization
* policy. In the absence of a stronger guarantee by the
* implementation, undefined behavior may result from the invocation
* of any method on a collection that is being mutated by another
* thread; this includes direct invocations, passing the collection to
* a method that might perform invocations, and using an existing
* iterator to examine the collection.
*
* <p>Many methods in Collections Framework interfaces are defined in
* terms of the {@link Object#equals(Object) equals} method. For example,
* the specification for the {@link #contains(Object) contains(Object o)}
* method says: "returns <tt>true</tt> if and only if this collection
* contains at least one element <tt>e</tt> such that
* <tt>(o==null ? e==null : o.equals(e))</tt>." This specification should
* <i>not</i> be construed to imply that invoking <tt>Collection.contains</tt>
* with a non-null argument <tt>o</tt> will cause <tt>o.equals(e)</tt> to be
* invoked for any element <tt>e</tt>. Implementations are free to implement
* optimizations whereby the <tt>equals</tt> invocation is avoided, for
* example, by first comparing the hash codes of the two elements. (The
* {@link Object#hashCode()} specification guarantees that two objects with
* unequal hash codes cannot be equal.) More generally, implementations of
* the various Collections Framework interfaces are free to take advantage of
* the specified behavior of underlying {@link Object} methods wherever the
* implementor deems it appropriate.
*
* <p>Some collection operations which perform recursive traversal of the
* collection may fail with an exception for self-referential instances where
* the collection directly or indirectly contains itself. This includes the
* {@code clone()}, {@code equals()}, {@code hashCode()} and {@code toString()}
* methods. Implementations may optionally handle the self-referential scenario,
* however most current implementations do not do so.
*
* <p>This interface is a member of the
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
* Java Collections Framework</a>.
*
* @implSpec
* The default method implementations (inherited or otherwise) do not apply any
* synchronization protocol. If a {@code Collection} implementation has a
* specific synchronization protocol, then it must override default
* implementations to apply that protocol.
*
* @param <E> the type of elements in this collection
*
* @author Josh Bloch
* @author Neal Gafter
* @see Set
* @see List
* @see Map
* @see SortedSet
* @see SortedMap
* @see HashSet
* @see TreeSet
* @see ArrayList
* @see LinkedList
* @see Vector
* @see Collections
* @see Arrays
* @see AbstractCollection
* @since 1.2
*/
public interface Collection<E> extends Iterable<E> {
​ ...
｝​

描述部分：指的是用语言描述功能的部分。

• 第一行应该是一句对类、接口、方法等的简单描述，这句话最后会被javadoc工具提取并放在索引目录中。如果是多句话，工具也只会提取第一句话。
• 支持HTML语法标签，比如：\xxx\ \

  分段\

• 支持特殊规定的标签，比如： {@link xxx} ，这种语法规则是{@标签名 标签内容}
• 还有很多注释风格的说明
  
  • 用 \关键字\ 来强调关键字，强调如：java关键字，包名，类名，方法名等
  • 控制 {@link xxx} 的数量，太多的跳转会让读者抓狂的
  • 描述一个方法时，应当只保留方法名字，不要附带方法的参数
  • 英文注释可以是短语也可以是句子。如果是句子，首字母要大写，如果是短语，首字母小写。
  • 方法的注释应该以动词或动词词组开头，因为方法是一个动作
  • API名应该是能够简单自我说明的
  • 尽量不要使用缩写

标记部分：指的是用标记符号如@param@return@see之类来描述的部分。

• @author 作者，没有特殊格式要求，名字或组织名称都可以
• @version 软件版本号（注意不是java版本号），没有特殊格式要求
• @param 方法参数，格式为： @param 参数名称 参数描述
• @return 方法返回值，格式为： @return 返回值描述 ，如果方法没有返回值就不要写@return
• @deprecated 应该告诉用户这个API被哪个新方法替代了，随后用 @see 标记或 {@link} 标记指向新API
• @throws （或 @exception ）包含方法显式抛出的检查异常(Checked Exception)，至于非显示抛出的其他异常(Unchecked Exception)，除非特别有必要，否则就别写了。

---

参考资料：
单行注释和多行注释
如何写Java文档注释(Java Doc Comments)