代码重构:注释(Comments)

举报
孙小北 发表于 2022/04/30 16:10:10 2022/04/30
【摘要】 什么是注释的坏味道(Comments)定义:1.某段代码有大段的注释,这些注释之所以存在是因为代码很糟糕2.代码注释错误,或者缺少必要的注释[1]影响: 以注释掩盖了代码坏味道,或者没有正确的注释,不便阅读。影响了代码的可读、可维护性改进目标: 消除不必要的注释,补充必要的注释,提升代码可读可维护性方法1.提取变量(代码段注释)2.提取方法(代码段注释)3.方法/变量改名(方法/变量注释)...

什么是注释的坏味道(Comments)

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

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

问题

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

image-20220429225542029.png

案例1:改进目标

重构目标

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

修改方案

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

image-20220429225554332.png

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

症状/问题

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

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

重构目标

  • 补充或修改注释

思考:要有效注释,但不建议消除注释

实际问题:不是注释多了,而是注释少了,有效注释更少

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

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

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

规范及工具

image-20220429225858120.png

总结

image-20220429225911967.png

  • 注释本身非坏味道,只是不合理的使用注释,会隐藏代码潜在的问题,掩盖了代码的坏味道
  • [1]《重构》一书中并没有这一条,但实际代码中经常会存在缺少必要注释、注释错误等情况,比如Javadoc、算法注释等,因此专门列出
    [2]同[1]
【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息, 否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。