今天看的是注释

什么时候不需要注释

1. 没有价值的注释

   这里只说一种看起来很高级，实际上没什么用的注释

   /*
   * @author DONG
   * @param BigDecimal number
   * @return String
   */
   public String translate(BigDecimal number) {
     
   }
   

   这种注释好像还有一种特定的名字，在我们的系统中比较少见，开源项目中经常见到。写这种注释一定是为了解释说明一些内容，比如这个方法的作用是什么(当然这个最好还是通过函数名告诉其他人)，以及入参出参具体什么表意或者例子。像上面这个，写的就没有必要

   尤其是一些如果不举例只看代码很难看懂的函数。比如我之前写过处理解析对方系统发过来的文件名，一会split("_")[1]，一会subString(1, 8)。这个函数我就把入参和对应的出参就写了一个例子。还有一种情形是正则表达式，这个东西功能非常强大，相对应的可读性也非常差。我们的日期工具类里判断日期的格式就用了正则表达式，好像每一种形式的判断上都加了一个例子的注释

2. TODO

   TODO注释作者其实是放在应该写的范畴里的，我放在这里是我觉得，很多人写了之后也不会去管它了。我曾经在代码库里全局搜过TODO，没记错了话搜出来了几百个。而且看代码的时候经常会看到，13、14年的代码，上面还写着TODO、FIXME、UNCHECKED。UNCHECKED的方法还有不少引用。这就足够说明其实我们应该写代码的时候就尽量把代码写完，要不就有一个去follow自己标记的内容的习惯。不然其实写TODO注释就没有什么用

3. 搞笑的注释(来自之前看的一篇推送文章)

   // 亲爱的维护者：
   // 一旦你尝试“优化”了这个程序，
   // 并意识到这是一个非常可怕的错误，
   // 为了警告后来人，
   // 请增加以下计算器：
   // total_hours_wasted_here = 42
   

什么时候应该写注释

1. 常量

   常量也要视情况而定，我们大多数定义的常量都是一个类里面的私有常量，仅仅是为了满足"不要使用魔法值"这一条规则而定义的，如果命名足以表达它的意思的话，就不用写注释了，下面这种其实就不用写注释

   public class BatchInsertTariffByRawSqlHelper {
     
     private static final Integer EACH_TIME_BATCH_PROCESS_TARIFF_COUNT = 5000;
     
     public void insertTariffs(List<String> tariffIds) {
       ListUtil.splitList(tariffIds, EACH_TIME_BATCH_PROCESS_TARIFF_COUNT).forEach(this::batchInsertEachGroupTariffs);
     }
     
     private void batchInsertEachGroupTariffs(List<String> tariffIds) {
       
       
     }
     
   }
   

   需要写注释的常量应该是大家都会用到的共有常用变量，比较典型的判断方法是，你单独写了一个类用于罗列这些常量，或者定义了一个公共的枚举类。这种情况下每一个常量都应该用注释解释业务含义以及使用场景

2. 专有名词

   这个也是之前碰到的一个例子，做profile的时候要刷新证件，我就需要看每一种证件对应的DB字段是哪个。这些证件名称都是专有名词，汽化罐什么什么使用资格证之类的。好在我看到数据库里面之前做这块的人已经给每一个字段都设好了comment了，帮我节约了不少时间对字段

3. 提示警告

   之前开发的时候碰到的一个比较好的例子，有一个非常复杂的查询，在最开始的Vo转criteria进行字段赋值的方法上，写了一段注释：这里添加字段的话，需要同步修改.....。如果没有这段注释，我肯定不会把整套查询代码看完的，这样就会影响后面的逻辑，而我自己却很难发现。

4. 解释说明

   碰到比较复杂的逻辑的时候，适当的在方法上解释说明会帮助后面的人理解代码逻辑。比如之前为了解决级联报错，我们选择了单起一个线程执行trigger逻辑。让一个不了解情况的人直接看代码，一定是看不懂为什么需要特别单起一个线程的。

写注释就是为了提醒自己，时刻要考虑后面维护这段代码的人的阅读。要在不增加别人阅读工作量的前提下，写精简的注释帮助后续其他人理解代码逻辑