先来灵魂一问，大家平时开发，写不写注释的都，我先来，方法加注释？不存在的。类注释？想多了。网络请求解析实例元素注释，这个确实要写点，不然都不知道是个什么玩意。不要说什么字段名就是最好注释，这个的前提是，用词准确并且阅读理解的水平相近，不然，那就是呵呵。

那么大家为什么不爱写注释，至少我自己不爱写就几个原因，1 懒。2 快速迭代就够烦了，谁还折腾这个，bug都还没改完呢。3 光我一个人写，其他小伙伴不写也没劲啊，我自己写的代码，写不写注释我自己都还有点印象，我写了注释，只是方便其他人理解，我自己接手修改别人负责的内容时，还是没注释啊，注释写得不够明白的不也折腾。4 注释其实是需要更新的，尤其是方法注释，某个版本修改某个功能后，如果注释忘记更新，那也是会有误导性的，尤其是注释参数需要足够明确参数范围和用法。

但是注释真的能一点都不写吗，那肯定不行的，坑人坑己，时间长了自己坑自己，所以我总结了下，在最懒的情况下，有这么些注释是值得去写的，而且基本是一次性的，创建的时候顺手写上完全不碍事，并且最好强制同项目小伙伴严格执行。结合实际来说，我经常遇到后台，测试，产品，拿着手机就过来问，这个页面的这个啥能不能改，这个页面用到了哪些接口..等等等等。一般来说，如果这个页面刚好是自己做的，那还有点印象，在哪个包，哪个Activity或者Fragment，但如果不是，那就只能，等等我先找找，每次都这样不累么。其实基本上大部分应用，每个activity或者fragment对应的都是特定职能的页面，而且大多数页面都是有标题的，比如什么，"设置"页面，"修改XX密码"页面，"关于"页面等等。所以，在创建类的时候，顺手写上是值得且有用的。
比如：

 /**
 * 总资产页面
 */
 public class TotalAssetActivity extends BaseActivity{}
/**
 * 历史消息页
 */
public class FragmentHistoryMessageHome extends BaseFragment{}

诸如类似，这样以后不管谁找来，只要主题明确，在studio中ctrl+h一把就能快速定位

图1

重点就是注释明确不要瞎写，结合应用体现中心主题，别瞎搞不好理解的就行。

第二类非写不可的注释，那就是网络接口定义注释，还是实际问题。
后端同事：能不能帮我看看这个接口哪些页面会调用到。
我：？？什么接口。
同事：查询XX数据的接口。
我：哦，等我先找找这个接口定义在哪。
然后找到后再来一顿ctrl+g搜索一把，最后找到定位。

那么如果加了注释，会不会方便很多呢。由于大部分接口职责单一的特殊性，其实道理和activity一样的，创建的时候，就决定了这个接口是干嘛用的，需求会明确到那些界面会使用，并且这个作用后期并不大可能修改，涉及到修改的，通常考虑兼容性会选择新增功能接口，所以这个注释也是可以在一开始就确定的。
比如

   /**校验短信验证码
   * @since v1.5
   * @see com.xxx.xxx.ui.dialog.sms.CommonSMSCodeDialogEventHandler
   * @see com.xxx.xxx.ui.fragment.VerifySMSFragment
   */
  public final class CheckSMSCodeRequest extends BaseRequest<CheckSMSCodeResult> {}

主要推荐两个元素 1 功能描述，这个接口用来干嘛的写清楚（特别强调，推荐写在文档注释第一行） 2 文档注释中的 @see 标记，其实改成{@link}也可以。使用see标记，能够使文档注释直接点击跳转到指定的页面类，而且写注释的时候这个过程是便捷化的，并不用一个字一个字敲，基本向上面的，打个@see verify，studio就智能引出可选类了，谁用谁知道。
可选标记@since 这个是个人习惯问题，哪个接口，是哪个版本迭代才增加的，标记一下，顺手的事，方便事后分析，因为会有同类型接口在某个新版本加入，用来逐步替代某个版本的老接口，但是有些人又不清楚的，会需要区分，同时老接口打上@Deprecated 。
当所有定义的接口都严格注释后，新世界来了，android studio下选中代码主包，然后来这么一下

图2

别忘了加参数 -encoding utf-8 -charset utf-8

图3

图4

最后，愿大家接盘项目都有注释，只要人人做到了写好注释，那在填坑的路上，不至于一脚踩得太深。