android开发注释规范

------有些人可能去公司开发了很长时间，但是不知道怎么去写各种文档，我在本章节给出了《安卓注释规范文档》的示例，仅供大家参考，如有不足请多指正。

 

 

 

XX产品Android注释规范

 

 

 

 

 

 

 

 

创建时间：xxxx-xx-xx

创 建 人：android开发组

 

 

 

 

 

 

修订时间	修订人	修订内容

1. 类、接口注释的内容

1、用途。开发人员使用某个类/接口之前，需要知道采用该类/接口的用途

2、开发维护的日志。一个有关于该类/接口的维护记录：时间、作者、摘要。

1) 文件头注释

   /*

* 文 件 名：LoginActivity

* 描    述：对用户

* 作    者：

* 时    间：

* 版    权：XX公司

*/

具体方法：以androidstudio为例

File->Settings搜索File and Code Templates 右边面板，Templates->Class然后修改编辑框里的内容

#if (${PACKAGE_NAME} && ${PACKAGE_NAME} != "")package ${PACKAGE_NAME};#end   /**  * 文件名：  * 描  述：  * 作  者：  * 时  间：  * 版  权：XX公司  */   public class ${NAME} {   }

2. 方法头注释

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

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

1、该方法是做什么的 。

2、传入什么样的参数给这个方法。@param

3、异常处理。@throws

4、这个方法返回什么。@return

/*

 * 方 法 名：login_Click(View v)

 * 功    能：单击登录按钮的事件

 * @param： v -按钮的View

 * @return：无

 * @throws：无

 * @data：

 */

步骤

1.File->Setting->Editor->Live Templates

2.点击+，创建一个Template Group

 

3.填个你要的group名，我的叫custom

 

4.选中你刚刚创建的group，创建Live Template

 

5填写Abbreviation,我这里填的是cmt,也即你这个注释的快捷方式，你敲cmt加回车，模板就出来了Template text是注释的模板，具体你模板要怎么写都可以，我的模板如下

 

6.注意到，我的Template text有定义了三个变量desc,date,time,后面两个我要生成日期和时间，所以我们要编辑这两个变量

点击Edit variables，在弹窗里分别为date和time就是设置对应的方法，date()这个方法会生成日期，time()这个方法会生成时间

 

7.点击Apply一切完成。现在，你只要在方法名上敲上cmt回车，就会自动生成注释模板了，效果如下，时间是自动生成的

 

3.覆盖（重写）成员方法注释

/** @覆盖父类或实现接口的onTouchEvent（MotionEvent event）方法   *方法名：   *工  能：   *参  数：   *返回值：   *参  考：   */  @override  Public boolean onTouchEvent(MotionEvent event){   }

4.属性getter和setter成员方法注释

/**      *属 性：webSite-getWebSite()，setWebSite(String)   *工 能：读、写属性webSite值   *说 明：String webSite -成员变量值说明   */  Public String getWebSite(){    return WebSite; }  Public String setWebSite(String webSite){    WebSite = webSite  ; }

5.块注释

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

{ Map<String,String> map = null; Cursor cursor = null; List<Map<String,String>> lists = null; try{      lists = new ArrayList<Map<String,String>>();      cursor = db.rawQuery(“......”,null);      //循环便利cursor，把数据存储到List<Map<String,String>>中      if (cursor!=null && cursor.getCount()>0){         .....      } } }

 

6.变量注释

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

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

public class Event{    public static final int GET_DEALS = 0;//获取产品    public static final int SHOW_HOME = 1;//显示首页代码    Public String final int SHOW_URL = 2;//显示网页 }

2. 局部变量注释的注释范例如下：

public InputStream  open(){   InputStream inputStream = null;   try{      String webUrl = “http://www.meituan.com/api/v2/beijing/deals”; //所连接的网址      URL url = new URL (webUrl); //根据网址创建URL对象         } }

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

private void sendQueryMessage(String city, String keywords){   //向控制器发送获取今日产品信息的消息   Message message = new Message();//创建要传递的消息对象   message .what = Event.GET_DEALS;//消息类型    }

7.有关注释的其它说明

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

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