Java&Android代码注释规范

一、注释及简介

    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 的三种句法：

<span style="white-space:pre"></span>@see 类名 <span style="white-space:pre"></span>@see #方法名或属性名<span style="white-space:pre"></span>@see 类名#方法名或属性名

2、使用 @author、@version 说明类
这两个标记分别用于指明类的作者和版本。这两个标记的句法如下：
　　

       @author 作者名　　   @version 版本号

　　 其中，@author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次，只有第一次有效，生成的文档中只会显示第一次使用 @version 指明的版本号。

3、使用 @param、@return 和 @exception 说明方法
这三个标记都是只用于方法的。@param 描述方法的参数，@return 描述方法的返回值，@exception 描述方法可能抛出的异常。它们的句法如下：

<span style="white-space:pre"></span>@param 参数名 参数说明<span style="white-space:pre"></span>@return 返回值说明<span style="white-space:pre"></span>@exception 异常类名 说明

每一个 @param 只能描述方法的一个参数，所以，如果方法需要多个参数，就需要多次使用 @param 来描述。
一个方法中只能用一个 @return，如果文档说明中列了多个 @return，则 javadoc 编译时会发出警告，且只有第一个 @return 在生成的文档中有效。方法可能抛出的异常应当用 @exception 描述。由于一个方法可能抛出多个异常，所以可以有多个 @exception。每个 @exception 后面应有简述的异常类名，说明中应指出抛出异常的原因。需要注意的是，异常类名应该根据源文件的 import 语句确定是写出类名还是类全名。

七、类注释

1.类注释

/*** 类 <code>{类名称}</code>{此类功能描述}* @author   {作者}* @version {版本,常用时间代替}* @see      java.lang.Class* @since    JDK{jdk版本} 或者编辑日期*/  

public class Object {}
2.类变量注释 

/** 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/

欢迎大家指正和沟通，谢谢大家！