代码重构:注释(Comments)
【摘要】 什么是注释的坏味道(Comments)定义:1.某段代码有大段的注释,这些注释之所以存在是因为代码很糟糕2.代码注释错误,或者缺少必要的注释[1]影响: 以注释掩盖了代码坏味道,或者没有正确的注释,不便阅读。影响了代码的可读、可维护性改进目标: 消除不必要的注释,补充必要的注释,提升代码可读可维护性方法1.提取变量(代码段注释)2.提取方法(代码段注释)3.方法/变量改名(方法/变量注释)...
什么是注释的坏味道(Comments)
- 定义:
1.某段代码有大段的注释,这些注释之所以存在是因为代码很糟糕
2.代码注释错误,或者缺少必要的注释[1] - 影响: 以注释掩盖了代码坏味道,或者没有正确的注释,不便阅读。影响了代码的可读、可维护性
- 改进目标: 消除不必要的注释,补充必要的注释,提升代码可读可维护性
- 方法
1.提取变量(代码段注释)
2.提取方法(代码段注释)
3.方法/变量改名(方法/变量注释)
4.补充/修改必要的注释[2] - 注:[1] [2]《重构》一书中并无此条,但业务代码中确实存在缺少必要注释、注释错误等情况,比如Javadoc、算法注释等,因此专门列出
案例1:通过注释隐藏坏味道
问题
- 试图通过注释来解释不易理解的代码
案例1:改进目标
重构目标
- 抽取变量、方法,并用合理的命名,实现代码的自注释
修改方案
- 提取变量:代码段的注释
- 提取方法:代码段的注释
- 方法/变量改名:方法/变量的注释
案例2:业务代码中其他一些常见注释问题
症状/问题
-
1.缺少必要的注释,包括缺少Javadoc或空有格式,算法代码缺少注释等
-
2.注释错误,注释与方法、参数、功能等不匹配
重构目标
- 补充或修改注释
思考:要有效注释,但不建议消除注释
实际问题:不是注释多了,而是注释少了,有效注释更少
- 缺乏有效的说明和注释
- 注释与代码实现不一致
- 为了注释而注释的冗余
- 晦涩难懂的低质量注释
有效日志:个人可追求代码即文档,但现阶段还是应该重视而不是消除注释
- 代码的基本功能描述
- 版本作者等基本信息
- 代码使用的前提和限制条件等
- 代码实现的特殊考虑和算法等
- 其他必要的代码说明
规范及工具
总结
- 注释本身非坏味道,只是不合理的使用注释,会隐藏代码潜在的问题,掩盖了代码的坏味道
- [1]《重构》一书中并没有这一条,但实际代码中经常会存在缺少必要注释、注释错误等情况,比如Javadoc、算法注释等,因此专门列出
[2]同[1]
【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)