代码重构：注释（Comments）

什么是注释的坏味道（Comments）

• 定义:
  1.某段代码有大段的注释，这些注释之所以存在是因为代码很糟糕
  2.代码注释错误，或者缺少必要的注释[1]
• 影响: 以注释掩盖了代码坏味道，或者没有正确的注释，不便阅读。影响了代码的可读、可维护性
• 改进目标: 消除不必要的注释，补充必要的注释，提升代码可读可维护性
• 方法
  1.提取变量（代码段注释）
  2.提取方法（代码段注释）
  3.方法/变量改名（方法/变量注释）
  4.补充/修改必要的注释[2]
• 注：[1] [2]《重构》一书中并无此条，但业务代码中确实存在缺少必要注释、注释错误等情况，比如Javadoc、算法注释等，因此专门列出

案例1：通过注释隐藏坏味道

问题

• 试图通过注释来解释不易理解的代码

案例1：改进目标

重构目标

• 抽取变量、方法，并用合理的命名，实现代码的自注释

修改方案

• 提取变量：代码段的注释
• 提取方法：代码段的注释
• 方法/变量改名：方法/变量的注释

案例2：业务代码中其他一些常见注释问题

症状/问题

• 1.缺少必要的注释，包括缺少Javadoc或空有格式，算法代码缺少注释等

• 2.注释错误，注释与方法、参数、功能等不匹配

重构目标

• 补充或修改注释

思考：要有效注释，但不建议消除注释

实际问题：不是注释多了，而是注释少了，有效注释更少

• 缺乏有效的说明和注释
• 注释与代码实现不一致
• 为了注释而注释的冗余
• 晦涩难懂的低质量注释

有效日志：个人可追求代码即文档，但现阶段还是应该重视而不是消除注释

• 代码的基本功能描述
• 版本作者等基本信息
• 代码使用的前提和限制条件等
• 代码实现的特殊考虑和算法等
• 其他必要的代码说明

规范及工具

总结

• 注释本身非坏味道，只是不合理的使用注释，会隐藏代码潜在的问题，掩盖了代码的坏味道
• [1]《重构》一书中并没有这一条，但实际代码中经常会存在缺少必要注释、注释错误等情况，比如Javadoc、算法注释等，因此专门列出
  [2]同[1]