代码重构：注释（Comments）

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

定义:

1.某段代码有大段的注释，这些注释之所以存在是因为代码很糟糕

2.代码注释错误，或者缺少必要的注释[1]

影响: 以注释掩盖了代码坏味道，或者没有正确的注释，不便阅读。影响了代码的可读、可维护性

改进目标: 消除不必要的注释，补充必要的注释，提升代码可读可维护性

方法

1.提取变量（代码段注释）

2.提取方法（代码段注释）

3.方法/变量改名（方法/变量注释）

4.补充/修改必要的注释[2]

注：[1] [2]《重构》一书中并无此条，但业务代码中确实存在缺少必要注释、注释错误等情况，比如Javadoc、算法注释等，因此专门列出

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

问题

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

案例1：改进目标

重构目标

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

修改方案

提取变量：代码段的注释

提取方法：代码段的注释

方法/变量改名：方法/变量的注释

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

症状/问题

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

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

重构目标

补充或修改注释

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

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

缺乏有效的说明和注释

注释与代码实现不一致

为了注释而注释的冗余

晦涩难懂的低质量注释

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

代码的基本功能描述

代码使用的前提和限制条件等

代码实现的特殊考虑和算法等

其他必要的代码说明

规范及工具

总结

注释本身非坏味道，只是不合理的使用注释，会隐藏代码潜在的问题，掩盖了代码的坏味道

[1]《重构》一书中并没有这一条，但实际代码中经常会存在缺少必要注释、注释错误等情况，比如Javadoc、算法注释等，因此专门列出

[2]同[1]

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。