Android开发规范：注释

我的新书《Android App开发入门与实战》已于2020年8月由人民邮电出版社出版，欢迎购买。点击进入详情

为了自己和他人阅读代码的方便，请做好注释。

文件头注释

文件顶部统一添加版权声明，声明的格式如下：

1. 示例

/**
 * Copyright (c) 2018 Your Company. All rights reserved.
 */

2. 设置
   路径：File → Settings → Editor → File and Code Templates → Includes → File Header
   
   然后在java文件中将这个文件包含进去，这样我们在新建java文件的时候，这个文件头注释也会自动生成。
   

类注释

1. 示例

/**   
* 对类的描述 
* @author:	张三   
* @e-mail:	xxx@xx
* @time:	${date}${time} 
* @version:	1.0
*/

2. 设置
   

方法注释

每一个成员方法（包括自定义成员方法、覆盖方法、属性方法）的方法头都必须做方法头注释。
在方法前一行输入**/**** + 回车，或者到AS中设置Fix doc comment(Settings → Keymap → Fix doc comment)快捷键，AS会帮我们自动生成模板，我们只需要补全参数即可。

/**   
* 对方法的说明   
* @param id 查询用ID  
* @return User实体类  
*/

通用注释

对于注释，我们还可以设定注释模板，然后通过快捷输入的方式自动帮我们生成设定的注释内容。
这样可以在代码的任何地方快捷生成注释，提升编码效率。

File → Settings → Editor → Live Templates，
新建一个MyComment的Group，然后建一个叫cmt的缩写，输入模板内容。
这样我们在代码里面输入cmt然后敲回车，就会自动帮我们生成模板内容。

方法体内代码注释

1. 对代码块注释

/***************** 说明 ******************/

2. 对单行注释

// 说明

3. 对多行注释

/*     
* 说明1     
* 说明2 
*/

常量变量的注释

下面几种情况下的常量和变量，都要添加注释说明，优先采用右侧//来注释，若注释说明太长则在上方添加注释。
接口中定义的所有常量
公有类的公有常量
枚举类定义的所有枚举常量
实体类的所有属性变量

public static final int TYPE_DOG = 1; // 狗
public static final int TYPE_CAT = 2; // 猫
public static final int TYPE_PIG = 3; // 猪

private int id; // id
private String name; // 名称
private String sex; // 性别

资源文件注释

<!-- Toast信息 -->

TODO注释

需要实现，但目前还未实现的功能说明。

//TODO 下个版本需要完成二期功能

FIXME注释

功能代码有问题，需要修复的说明。

//FIXME 返回值没有带上单位符号