Java和Android注释规范

1、 文件头注释

每一个文件的文件头都必须做文件头注释。文件头注释范例如下：

/*
* 文件名：LoginActivity
* 描    述：对用户
* 作    者：
* 时    间：
* 版    权：
*/

2、 方法头注释

每一个成员方法（包括自定义成员方法、覆盖方法、属性方法）的方法头都必须做方法头注释。

自定义成员方法注释范例如下：

/*
 * 方法名：login_Click(View v)
 * 功    能：单击登录按钮的事件
 * 参    数：View v - 按钮的View
 * 返回值：无
 */

3、覆盖（重写）成员方法注释范例如下：

/**
 * @覆盖父类或实现接口的onTouchEvent(MotionEvent event) 方法
 * 方法名：onTouchEvent(MotionEvent event)
 * 功能:触屏事件
 * 参数：MotionEvent event - 触屏事件源
 * 返回值：boolean - 是否撤销该事件
 * 参考：@see android.app.Activity#onTouchEvent(android.view.MotionEvent)
 */

4、属性getter和setter成员方法注释范例如下：

/**
 * 属性：webSite- getWebSite(),setWebSite(String)
 * 功能：读、写属性webSite值
 * 说明：String webSite - &成员变量值说明
 */

5、块注释

在实现一段阶段性功能的代码前做块注释。块注释的注释范例如下：

//循环遍历cursor,把数据存储到List<Map<String,String>>中

6、变量注释

所有的成员变量和大多数局部变量在声明时都需要为其做功能注释。

成员变量注释的注释范例如下：

例如: 

    /** use serialVersionUID from JDK 1.0.2 for interoperability */
    private static final long serialVersionUID = -6849794470754667710L;

这样做的好处是，生成java doc 文档时自动生成类成员的说明。从现象上来看，类的成员被加上文档注释之后，在Eclipse中鼠标放在成员变量，或成员方法上时，会有注释出现，

7、局部变量注释的注释范例如下：

8、语句注释

在关键语句的右侧要做单条语句注释。

语句注释的注释范例如下：

9、有关注释的其它说明

（1）   文件头和方法头注释应该使用/**/形式，变量注释和语句注释应该使用//形式，块注释应尽量使用//形式，当文字较长（单屏横向不能显示完全）时块注释也可以使用/**/形式；

（2）   注释量必须不少于代码总量的三分之一；