当我们谈起代码注释，估计你有以下反应：
1.老子的代码没别人看，不需要注释；
2.这段代码很简单，不需要注释；
3.这段代码很复杂，我多写些注释；
当你发现一段代码有bug，或者看到一坨很恶心的代码像重构，然而没有一点注释，可能会出现以下心理活动：
1.写这段代码的家伙（有可能是你自己）一点注释都不写，这bug怎么修？
2.这段代码做什么？需求是什么？找找需求文档...
3.参数啥意思？我找找接口文档先...
4.需求文档呢？接口文档呢？（好旧的需求）
当你发现一段代码有bug，还有注释：
1.幸好有注释，我知道它干什么；
2.草，注释说的跟代码不符合呀！
今天咱们聊聊，没写注释和写了注释也会出现的尴尬的问题。
请求api的注释
1.如果你公司有接口文档，你应该写注释；
2.如果你公司没接口文档，你更应该写注释。
举个的例子：
public interface Api {
@POST("/challenge/createActivity")
Observable<String> createActivity(@Field("activityStartTime") int activityStartTime, @Field("activityEndTime") int activityEndTime,
@Field("challengePoint") int challengePoint,
@Field("checkInNumRule") int checkInNumRule,
@Field("description") String description,
@Field("distanceRule") int distanceRule,
@Field("speedRule") int speedRule,
@Field("sumDistanceRule") int sumDistanceRule,
@Field("taskType") int taskType);
}
你知道createActivity方法是做什么的吗？直译的话，可以认为这是“创建一个活动”的接口。你知道每个参数含义吗？distanceRule checkInNumRule什么意思？反正没注释笔者是不知道。
这时，有工程师会：
安卓工程师：“找接口文档。”
笔者：“请问接口文档在哪？”
安卓工程师：“公司一般有接口文档管理网站，搜一下就好。”
“搜接口文档”看起来很简单的事，实际上，有那么简单吗？对于新项目，接口文档很好找，如果是老项目，接口文档管理网站可能已经换了，你还得问后端同事，旧网站网址。而且不是每个后端工程师都知道网址，可能得问老员工......
还有，如果每次阅读这段代码，都要查查接口文档，耗费工程师多少时间成本？
以下是笔者认为比较好的注释：
public interface Api {
/**
* 创建个人发起的挑战活动 http://doc.thejoyrun.com/api/challenge/createActivityForPersonal
*
* @param activityStartTime 挑战开始时间
* @param activityEndTime 挑战结束时间
* @param challengePoint 挑战积分
* @param checkInNumRule 打卡次数, 当taskType=2时，必填
* @param description 规则说明
* @param distanceRule 单次打卡距离, 当taskType=2时，必填
* @param speedRule 配速, 当taskType=1时，必填，整型，如配速 6分30秒，应传390
* @param sumDistanceRule 累计距离, 当taskType=1时，必填
* @param taskType 挑战类型, 1是累计距离挑战；2是打卡挑战；必填
*
* @return 创建成功返回msg
*/
@POST("/challenge/createActivity")
Observable<String> createActivity(@Field("activityStartTime") int activityStartTime, @Field("activityEndTime") int activityEndTime,
@Field("challengePoint") int challengePoint,
@Field("checkInNumRule") int checkInNumRule,
@Field("description") String description,
@Field("distanceRule") int distanceRule,
@Field("speedRule") int speedRule,
@Field("sumDistanceRule") int sumDistanceRule,
@Field("taskType") int taskType);
}
这样是不是清晰多了？方法功能、参数意义、接口文档网址都有了。工程师还能用Quick Documentation快速查看代码注释，节省工程师多少时间。
以下给出接口文档 (假的url)：http://doc.thejoyrun.com/api/challenge/createActivityForPersonal
接口名称 创建个人发起的挑战活动-（预设）
请求类型 post
请求Url /challenge/createActivity
| 变量名 | 含义 | 类型 | 备注 |
|---|---|---|---|
| activityEndTime | 挑战结束时间 | number | 必填 |
| activityStartTime | 挑战开始时间 | number | 必填 |
| challengePoint | 挑战积分 | number | 必填 |
| checkInNumRule | 打卡次数 | number | 当taskType=2时，必填 |
| description | 规则说明 | string | 必填 |
| distanceRule | 单次打卡距离 | number | 当taskType=2时，必填 |
| speedRule | 配速 | number | 当taskType=1时，必填，整型，如配速 6分30秒，应传390 |
| sumDistanceRule | 累计距离 | number | 当taskType=1时，必填 |
| taskType | 挑战类型 | number | 1是累计距离挑战；2是打卡挑战；必填 |
自动生成代码/注释
一份标准的文档，是有固定格式，笔者公司用RAP文档管理。笔者写了个用java代码根据文档生产代码+注释的小工具，繁琐、重复的工作，交给脚本生成就好。
Java Bean注释
1.当成员变量英文名或意义比较复杂，必写注释；
2.当成员变量数值有范围，或多个值且有特定意义，必写注释。
请看请求接口和返回列表
public interface Api {
/**
* 我的挑战列表 http://doc.thejoyrun.com/api/challenge/myChallenges
*/
@GET("/challenge/myChallenges")
Observable<List<Challenge>> getChallengeList();
}
/**
* 挑战
*/
public class Challenge {
int challengeId;
String title;
String imageCover;
int activityEndTime;
int activityStartTime;
int activityStatus;
int joinTime;
int timeLeft;
int userJoinStatus;
}
Challenge是挑战列表的元素。直译，猜到activityStatus 、userJoinStatus是两种状态，但这两种状态分别有什么数值呢？什么数值代表什么意思？
当你看到如下代码：
Challenge challenge = new Challenge();
switch (challenge.getActivityStatus()){
case 0:
// do something A
break;
case 1:
// do something B
break;
......
}
假如，测试工程师跟你说 活动进行中有bug，而你又不知道activityStatus哪种情况会执行A或B，那你就必须debug，或者查接口文档activityStatus哪个数值是 活动进行中。
还有，timeLeft直译“剩下的时间” ，是到哪个时间节点剩下的时间？
这些工作都会大量耗费工程师时间。如果我们把注释写好一点：
public class Challenge {
/** 挑战活动ID */
int challengeId;
/** 标题 */
String title;
/** 封面地址 */
String imageCover;
/** 挑战结束时间 */
int activityEndTime;
/** 挑战开始时间 */
int activityStartTime;
/**
* 挑战活动状态 0-未开始 1-进行中 2-已结束
*/
int activityStatus;
/** 用户报名挑战时间 */
int joinTime;
/** 挑战未开始的时候为距离开始的剩余时间；当挑战进行中的时候表示还剩余多少时间结束 */
int timeLeft;
/**
* 参与状态 -1失败 0-未参加 1-挑战中 2-挑战成功
*/
int userJoinStatus;
}
这样就清晰多了，直接Quick Documentation就可以查看activityStatus注释。你可以明确activityStatus==1时，才出现bug，直接定位到case 1出bug代码块。
还有，timeLeft在不同状态下，意义不同。1.挑战未开始，为距离开始的剩余时间；2.挑战进行中，表示还剩余多少时间结束。如果不写注释，谁知道这些啊？
Activity注释
如果给你一个Activity，完全没有注释：
@RouterActivity("page_x")
public class ActivityX extends AppCompatActivity {
......
}
Activity注解@RouterActivity表示外部可以通过page_x路由跳进来。
请问，这个Activity是从哪个界面跳进来的？
好运的话，Find Usages会找到startActivity(new Intent(context, ActivityX.class))，或者找到路由跳转page_x的位置。
给你个场景：ActivityX从A界面条进来，而A界面必须满足一定条件，才出现跳转page_x按钮。例如，A界面请求服务器，返回某个字段status=1满足条件。
再复杂一点，跳转路径：
C -> B -> A -> X
继续复杂点，page_x是后端返回的跳转路径，app不写死。在代码层面根本找不到入口。
你能一眼看出ActivityX是干什么的吗？
对于复杂的跳转路径，及满足条件才能跳转，我们非常难知道ActivityX的功能是什么。
如果我们在头部写上备注：
/**
* 参与过的活动详情。<br>
* 入口：我的活动，右上角“历史” -> 参与过的活动列表，点击item进入
*/
@RouterActivity("page_x")
public class ActivityX extends AppCompatActivity {
......
}
这样是不是清晰明了？
结语
本篇笔者就重点说了请求接口注释、java bean注释。读者应该举一反三：
1.java的方法要写注释，表明用途；
2.方法参数写注释，表明意义；
3.成员变量写注释，表明意义，数值范围，每个值的意义等.
每次笔者要修bug，当代码不是笔者写，而且又没有任何备注，恐怕会立即脱口而出“卧槽”！
写好注释不能让你从中级变高级工程师，但其他工程师阅读你的代码，知道你是一个做事谨慎细心的人，也让阅读的人赏心悦目。
不写注释有个笑话：
我写这段代码时，知道它在做什么的，只有老天和我；
但是现在，只有老天知道这段代码在做什么。
网友评论