一个程序的可读性，关键取决于注释。

Java 支持 3 种注释，分别是单行注释、多行注释和文档注释。文档注释以/**开头，并以*/结束，可以通过 Javadoc 生成 API 帮助文档，Java 帮助文档主要用来说明类、成员变量和方法的功能。

文档注释只放在类、接口、成员变量、方法之前，因为 Javadoc 只处理这些地方的文档注释，而忽略其它地方的文档注释。

1 类注释

类注释一般必须放在所有的import语句之后，类定义之前，主要声明该类可以做什么，以及创建者、创建日期、版本和包名等一些信息。以下是一个类注释的模板。

/**
 * @projectName（项目名称）: project_name
 * @package（包）: package_name.file_name
 * @className（类名称）: type_name
 * @description（类描述）: 一句话描述该类的功能
 * @author（创建人）: user 
 * @createDate（创建时间）: datetime  
 * @updateUser（修改人）: user 
 * @updateDate（修改时间）: datetime
 * @updateRemark（修改备注）: 说明本次修改内容
 * @version（版本）: v1.0
 */

提示：以上以@开头的标签为 Javadoc 标记，由@和标记类型组成，缺一不可。@和标记类型之间有时可以用空格符分隔，但是不推荐用空格符分隔，这样容易出错。

一个类注释的创建人、创建时间和描述是不可缺少的。下面是一个类注释的例子。

/**
 * @author: zhangsan
 * @createDate: 2018/10/28
 * @description: this is the student class.
 */
public class student{
    .................
}

注意：没有必要在每一行的开始用*。例如，以下注释同样是合法的：

/**
   @author: zhangsan
   @createDate: 2018/10/28
   @description: this is the student class.
 */
public class student{
    .................
}

2 方法注释

方法注释必须紧靠在方法定义的前面，主要声明方法参数、返回值、异常等信息。除了可以使用通用标签外，还可以使用下列的以@开始的标签。

@param 变量描述：对当前方法的参数部分添加一个说明，可以占据多行。一个方法的所有 @param 标记必须放在一起。
@return 返回类型描述：对当前方法添加返回值部分，可以跨越多行。
@throws 异常类描述：表示这个方法有可能抛出异常。

下面是一个方法注释的例子。

/**
 * @param num1: 加数1
 * @param num2: 加数2
 * @return: 两个加数的和
 */
public int add(int num1,int num2) {
    int value = num1 + num2;
    return value;
}

以上代码的 add() 方法中声明了两个形参，并将它们两个的和作为返回值返回。

3 字段注释

字段注释在定义字段的前面，用来描述字段的含义。下面是一个字段注释的例子。

/**
 * 用户名
 */
public String name;

也可以使用如下格式：

/**用户名*/
public String name;

在 Java 的编写过程中我们需要对一些程序进行注释，除了自己方便阅读，更为别人更好理解自己的程序。注释对于程序的可读性来说是非常重要的，希望读者不要忽视它。

4 看看官方用例

package java.util;

/**
 * This class contains various methods for manipulating arrays (such as
 * sorting and searching). This class also contains a static factory
 * that allows arrays to be viewed as lists.
 *
 * <p>The documentation for the methods contained in this class includes
 * briefs description of the <i>implementations</i>. Such descriptions should
 * be regarded as <i>implementation notes</i>, rather than parts of the
 * <i>specification</i>. Implementors should feel free to substitute other
 * algorithms, so long as the specification itself is adhered to. (For
 * example, the algorithm used by {@code sort(Object[])} does not have to be
 * a MergeSort, but it does have to be <i>stable</i>.)
 *
 * <p>This class is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @author Josh Bloch
 * @author Neal Gafter
 * @author John Rose
 * @since  1.2
 */
public class Arrays {
 
    /**
     * Sorts the specified array into ascending numerical order.
     *
     * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
     * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
     * offers O(n log(n)) performance on many data sets that cause other
     * quicksorts to degrade to quadratic performance, and is typically
     * faster than traditional (one-pivot) Quicksort implementations.
     *
     * @param a the array to be sorted
     */
    public static void sort(int[] a) {
        DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
    }
}