Android到底要不要写注释

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

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

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

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

诸如相似，这样之后无论谁找来，只要主题明确，在studio中ctrl+h一把就能快速定位

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

第二类非写不可的注释，那就是网络接口定义注释，仍是实际问题。 后端同事：能不能帮我看看这个接口哪些页面会调用到。 我：？？什么接口。 同事：查询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下选中代码主包，而后来这么一下

别忘了加参数 -encoding utf-8 -charset utf-8 就会获得一份传统的java doc文档，没有注释的类咱们无论，我接口都放在同一个子包下，程序包中选中接口所在包，随便选一个接口类切换到程序包，就会看到

而且点击进去后，能够很方便的看到该接口用在了哪两个类

结合一开始说的页面注释，已经方便不少了，这样至少之后别人问起来，或者本身找起来，再也不那么狗血。 最后说一下，定义接口解析实例对象的字段属性，也必定要注释，否则，谁来都受不了，哪怕只是漏一个，之后都有多是坑，人员来来去去，彻底不知道这个字段是什么意思，要去翻用在哪，怎么用，来反推这个字段的意义，贼坑啊。

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