我的注释我做主

周大仙人 发表于 2020/11/02 19:56:22 2020/11/02
【摘要】 我看了那么多年代码,也就看了那么多年注释。可以说,好代码不一定有好注释,但烂代码基本和烂注释共存。下面就是我认为的常见的烂注释风格,排名分先后: 1. 注释上带联系方式,TODO事项,问题单需求链接等。这种风格其实体现了工程师没有意识去利用好现代的平台技术,还停留在90年代的编码习惯。2020年了,git类软件已经是软件开发的首选代码托管平台了,问题单需求链接和联系方式的最佳位置...

   我看了那么多年代码,也就看了那么多年注释。可以说,好代码不一定有好注释,但烂代码基本和烂注释共存。下面就是我认为的常见的烂注释风格,排名分先后:

    1. 注释上带联系方式,TODO事项,问题单需求链接等。这种风格其实体现了工程师没有意识去利用好现代的平台技术,还停留在90年代的编码习惯。2020年了,git类软件已经是软件开发的首选代码托管平台了,问题单需求链接和联系方式的最佳位置应该是Git的提交日志上,TODO事项应该使用Git的issue管理。这种注释看到就应该删掉。例如以下两种注释

    2. 注释上带有一部分设计内容。这些内容最大的问题是,没人知道它是真是假,更没人知道它是否完整,删掉了吧,又有点可惜,万一有点用呢?不删吧,又看着不舒服。出现这种问题的最大原因是,团队内没有太好的地方承载这类文档。2020年了,可以试试Github的pages平台。

    3. 注释上写how,而不是why。这种大家都很清晰了,一致认为是不应该的。我就不多说了,参考下面的例子

    4. 对代码的使用说明,例如方法如何调用,各项参数的说明,会抛出什么异常。例如以下的例子便是。有空写这种注释,还不如把测试用例写好,通过用例来告诉用户应该如何使用。

    5. 代码某种算法的特殊说明,这种比较有争议性,严格来说,不算是烂注释,但如果这种注释没有严格和代码一起管理(例如改了代码要同步改注释),那么这种注释就没有好过有了。所以这虽然严格来说是一个管理原因,但2020年了,我更推荐把这种注释写到提交日志上。怎么说呢?我以Git的这段提交来说明这个问题,这段提交只设计到一个变量的非null判断,很多人可能就直接提交了,有些人也会在代码上加上注释,阐述为什么要做这个非null判断,但作者最终是选择了在提交日志上阐述这段逻辑,而且足足写了20行(刨去一些个人签名,有效行数也很多),想象一下把这20行写到代码中,会对代码的阅读产生多大的影响呀?但不写,又会对后面的维护带来问题。

   

【版权声明】本文为华为云社区用户原创内容,转载时必须标注文章的来源(华为云社区),文章链接,文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件至:cloudbbs@huaweicloud.com进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容。
  • 点赞
  • 收藏
  • 关注作者

评论(0

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

全部回复

上滑加载中

设置昵称

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

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

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