编写代码注释的最佳实践
作者 | Ellen Spertus
译者 | 王雪迎
出品 | CSDN(ID:CSDNnews)
虽然有很多资源可以帮助程序员编写更好的代码,比如书籍或静态分析器,但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易,但衡量注释的质量却很难,而且两者并不一定相关。差的注释比根本不写注释更糟糕。这里有一些规则可以帮助你实现一种折中的方法。
麻省理工学院的著名教授Hal Abelson曾说过:“程序必须写给人们阅读,而只是附带地让机器执行。”虽然他可能故意低估了运行代码的重要性,但却注意到了程序有两种截然不同的受众。编译器和解释器会忽略注释,找出同等容易理解的所有语法正确的程序。而人类读者则完全不同。我们发现有些程序比其它的更难理解,此时就会通过查看注释来帮助我们理解这些程序。
虽然有很多资源可以帮助程序员编写更好的代码,比如书籍或静态分析器,但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易,但衡量注释的质量却很难,而且两者并不一定相关。差的注释比根本不写注释更糟糕。正如Peter Vogel所述:
编写并维护注释是一项开销。
编译器不会检查注释,因此无法确定注释是否正确。
另一方面,你可以保证计算机完全按照你的代码所示运行。
所有这些观点都是正确的,但如果走到另一个极端,即从不写注释,那将是一个错误。这里有一些规则可以帮助你实现一种折中的方法:
规则1:注释不应与代码重复。
规则2:好的注释不能成为代码不清晰的借口。
规则3:如果无法写出一个清晰的注释,代码可能有问题。
规则4:注释应该消除混乱,而不是引起混乱。
规则5:在注释中解释不规范的代码。
规则6:提供复制代码的原始出处链接。
规则7:在可能提供帮助的地方引入指向外部参考的链接。
规则8:在修复bug时添加注释。
规则9:使用注释来标记未完成的实现。
本文其余部分将逐条解释这些规则,提供示例并说明如何以及何时应用它们。
规则1:注释不应与代码重复
许多初级程序员会写太多注释,因为他们接受了入门指导老师的培训。我曾见过计算机科学系的高年级学生为每对大括号加上一条注释,以表示该块结束:
if (x > 3) {…
} // if
我也听说过老师要求学生对每一行代码进行注释。虽然这对极为初级者来说可能是一个合理的策略,但这样的注释就像是训练轮,在大孩子骑车时应该去掉。
不添加任何信息的注释具有负价值,因为它们:
增加视觉混乱
读写花时间
可能会过时
一个典型的坏示例为:
i = i + 1; // Add one to i
它不添加任何信息,并切产生维护成本。
每一行代码都需要注释的策略在Reddit上都受到了相当的嘲笑:
// create a for loop // <-- comment
for // start for loop
( // round bracket// newline
int // type for declaration
i // name for declaration
= // assignment operator for declaration
0 // start value for i
规则2:好的注释不能成为代码不清晰的借口
注释的另一个误用是提供本应包含在代码中的信息。一个简单的例子是,有人用一个字母命名一个变量,然后添加一个描述其用途的注释:
private static Node getBestChildNode(Node node) {Node n; // best child node candidatefor (Node node: node.getChildren()) {// update n if the current state is betterif (n == null || utility(node) > utility(n)) {n = node;}}return n;
}
通过更好的变量命名,可以不需要再做注释:
private static Node getBestChildNode(Node node) {Node bestNode;for (Node currentNode: node.getChildren()) {if (bestNode == null || utility(currentNode) > utility(bestNode)) {bestNode = currentNode;}}return bestNode;
}
正如Kernighan和Plauger在编程风格要素一书中所写,“不要注释糟糕的代码 — 重写它。”
规则3:如果无法写出一个清晰的注释,代码可能有问题
Unix源代码中最臭名昭著的注释是“你不希望理解它”,它出现在一些恐怖的上下文切换代码之前。Dennis Ritchie后来解释说这是故意为之:“本意是想表达‘这不会出现在考试中’,而不是作为一种厚颜无耻的挑战。”不幸的是,结果发现他与合作者Ken Thompson自己也理解不了,后来不得不重写。
这让人想起了Kernighan定律:
调试在一开始就比编写程序困难一倍。因此,按照定义,如果你的代码写得非常巧妙,那么你就没有足够的能力来调试它。
警告读者远离你的代码就像打开汽车的危险警示灯:承认你正在做知法犯法的事情。相反,把代码重写成你充分理解的东西,或者更进一步,直截了当地进行解释。
规则4:注释应该消除混乱,而不是引起混乱
如果没有Steven Levy的 黑客:计算机革命的英雄 中的这个故事,任何关于负面注释的讨论都是不完整的:
[Peter Samson]拒绝在源代码中添加注释来解释他在特定时间所做的事情,使其特别晦涩难懂。在一个分发良好的程序中,Samson继续编写了数百条汇编语言指令,其中只有一条包含1750数字的指令带有注释。注释是RIPJSB,人们绞尽脑汁研究它的含义,直到有人发现1750年是巴赫去世的那一年,而Samson写的注释是Rest In Peace Johann Sebastian Bach(安息吧,约翰·塞巴斯蒂安·巴赫)的缩写。
虽然我和别人一样欣赏一个好的黑客,但这种注释不可效仿。如果你的注释引起混乱而不是消除混乱,删除它。
规则5:在注释中解释不规范的代码
注释掉其他人可能认为不需要或冗余的代码是个好主意,比如来自App Inventor的代码(我所有的正面示例均源于此):
final Object value = (new JSONTokener(jsonString)).nextValue();
// Note that JSONTokener.nextValue() may return
// a value equals() to null.
if (value == null || value.equals(null)) {return null;
}
如果没有注释,有人可能会“简化”代码或将其视为一个神秘但必不可少的咒语。写下为什么需要这些代码,可以节省未来读者的时间并解除他们的焦虑。
需要对是否注释代码做出判断。在学习Kotlin时,我遇到了Android教程中的代码:
if (b == true)
我立即想到是否可以用以下代码取代:
if (b)
就像在Java中一样。经过一点研究,我了解到可以为null的布尔变量会显式地与true进行比较,以避免出现难看的null检查:
if (b != null && b)
我建议不要为常见的语法添加注释,除非专门为新手编写教程。
规则6:提供复制代码的原始出处链接
如果你像大多数程序员一样,有时会使用网上找到的代码。包含对源代码的引用,可使将来的读者能够获得完整的上下文,例如:
解决了什么问题
谁提供了代码
为什么推荐此解决方案
评论者怎么看
是否仍然有效
如何改进
例如,考虑此注释:
/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */
点开链接,给出了以下信息:
代码的作者是Tomáš Procházka,他在Stack Overflow上排名前3%。
一个评论者提供了一个优化,已经纳入repo资源库。
另一位评论者提出了一种避免边缘情况的方法。
将其与下面的注释对比(稍作修改以防止侵权):
// Magical formula taken from a stackoverflow post, reputedly related to
// human vision perception.
return (int) (0.3 * red + 0.59 * green + 0.11 * blue);
任何想要理解这段代码的人都必须搜索公式。粘贴到URL要比以后查找引用快得多。
有些程序员可能不愿意表明他们自己并没有编写代码,但是重用代码是一个明智的举动,它可以节省时间并让你获得更多关注。当然,永远不要粘贴不懂的代码。
人们从Stack Overflow的问题和答案中复制大量代码。这些代码要求归属于知识共享许可下。引用注释满足该要求。
同样,你应该引用一些有用的教程以便再次找到它们,并且感谢它们的作者:
// Many thanks to Chris Veness at http://www.movable-type.co.uk/scripts/latlong.html
// for a great reference and examples.
规则7:在可能提供帮助的地方引入指向外部参考的链接
当然,并非所有引用都指向Stack Overflow。考虑:
// http://tools.ietf.org/html/rfc4180 suggests that CSV lines
// should be terminated by CRLF, hence the \r\n.
csvStringBuilder.append("\r\n");
到标准或其它文档的链接可以帮助读者理解代码正在解决的问题。虽然这些信息可能出现在设计文档中的某个地方,但一个适当位置的注释会在最需要它的时间和地方为读者提供标识。本例中,点开链接可以看到RFC 4180已经由RFC 7111更新了有用的信息。
规则8:在修复bug时添加注释
不仅应该在最初编写代码时添加注释,修改代码时,特别是修复bug时,也应该添加。看下面这个注释:
// NOTE: At least in Firefox 2, if the user drags outside of the browser window,// mouse-move (and even mouse-down) events will not be received until// the user drags back inside the window. A workaround for this issue// exists in the implementation for onMouseLeave().@Overridepublic void onMouseMove(Widget sender, int x, int y) { .. }
注释不仅有助于读者理解当前方法和引用方法中的代码,而且有助于确定是否仍然需要这些代码以及如何测试它们。
注释还可以帮助参考问题跟踪程序:
// Use the name as the title if the properties did not include one (issue #1425)
虽然 git blame 可以用来查找添加或修改行的提交,但提交消息往往很简短,最重要的更改(例如,修复问题#1425)可能不是最近提交(例如,将方法从一个文件移动到另一个文件)的一部分。
规则9:使用注释来标记未完成的实现
即使代码中有已知的限制,有时还是有必要检查它。虽然不分享代码中已知的缺陷很有诱惑力,但最好将这些明确化,例如使用TODO注释:
// TODO(hal): We are making the decimal separator be a period,
// regardless of the locale of the phone. We need to think about
// how to allow comma as decimal separator, which will require
// updating number parsing and other places that transform numbers
// to strings, such as FormatAsDecimal
对此类注释使用标准格式有助于衡量和解决技术负债问题。更好的办法是,在跟踪系统中添加一个问题,并在注释中引用该问题。
总结
我希望上面的例子已经表明,注释不能成为差代码的借口或修复差代码;它们通过提供不同类型的信息来补充好的代码。正如Stack Overflow联合创始人Jeff Atwood所写,“代码告诉你怎么做,注释告诉你为什么。”
遵守这些规则可以节省你及其队友的时间,减少挫折感。
即便如此,我确信这些规则并不是详尽无遗的,并期待着在评论中看到补充建议。
参考资料:
https://www.reddit.com/r/ProgrammerHumor/comments/8w54mx/code_comments_be_like/
https://www.reddit.com/r/ProgrammerHumor/comments/bz35nh/whats_a_comment/
https://geekandpoke.typepad.com/geekandpoke/2011/06/code-commenting-made-easy.html
https://geekandpoke.typepad.com/geekandpoke/2008/07/good-comments.html
https://www.commitstrip.com/en/2016/09/01/keep-it-simple-stupid/?
https://www.commitstrip.com/en/2013/07/22/commentaire-de-commit/?
https://geekandpoke.typepad.com/geekandpoke/2009/07/
https://geekandpoke.typepad.com/geekandpoke/2010/11/architecture.html
原文链接:https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/
声明:本文由CSDN翻译,转载请注明来源。
60+专家,13个技术领域,CSDN 《IT 人才成长路线图》重磅来袭!
直接扫码或微信搜索「CSDN」公众号,后台回复关键词「路线图」,即可获取完整路线图
编写代码注释的最佳实践相关推荐
- 最佳实践系列:前端代码标准和最佳实践
最佳实践系列:前端代码标准 @窝窝商城前端(刘轶/李晨/徐利/穆尚)翻译于2012年 版本0.55 @郑昀校对 isobar的这个前端代码标准和最佳实践文档,涵盖了Web应用开发的方方面面,我们翻译了 ...
- [Client]前端代码规范 及 最佳实践
前端代码规范 及 最佳实践 2014/10/29 | 分类: WEB前端, 工具与资源, 开发 | 0 条评论 | 标签: 代码规范, 前端开发, 最佳实践 分享到: 62 本文作者: 伯乐在线 - ...
- git拉取tag代码_10年经验17张图带你进入gitflow企业项目代码版本管理的最佳实践...
前言 对于项目版本管理,你是否存在这样的痛点:项目分支多而杂不好管理,git log界面commit信息错乱复杂无规范,版本回退不知道选择什么版本合适--. 项目版本管理的最佳实践系列,笔者将以两篇文 ...
- 5个让前端代码变得简洁的最佳实践
「每天一点小知识,天天学习好孩子」 欢迎来到学习章节:5个让前端代码变得简洁的最佳实践 "即使错误的代码也可以起作用.但是,如果代码不干净,则会使开发组织屈服." -罗伯特·马丁( ...
- 编写 Shell 脚本的最佳实践
转自:http://kb.cnblogs.com/page/574767/ 前言 由于工作需要,最近重新开始拾掇shell脚本.虽然绝大部分命令自己平时也经常使用,但是在写成脚本的时候总觉得写的很难看 ...
- [转载]前端代码规范 及 最佳实践
http://blog.jobbole.com/79075/#_general_practices 本文作者: 伯乐在线 - 老码农 .未经许可,禁止转载! 欢迎分享原创到伯乐头条. 本文来自 Iso ...
- 在SDLC中使用静态代码分析的最佳实践
http://vultrace.cn更多精彩,尽在个人博客. 文章翻译自ncc group的论文,论文超长预警,请耐心观看. Best Practices for the use of Static ...
- 前端代码规范及最佳实践
本文来自 Isobar公司 的 github repo 中文版 翻译: @老码农的自留地 概述 本文档包含了Isobar公司的创意技术部(前端工程)开发web应用的规范.现在我们把它开放给任何希望了解 ...
- 前端代码规范 及 最佳实践
本文来自 Isobar公司 的 github repo 中文版 翻译: @老码农的自留地 概述 本文档包含了Isobar公司的创意技术部(前端工程)开发web应用的规范.现在我们把它开放给任何希望了解 ...
最新文章
- win10恢复经典开始菜单_小编教你电脑如何升级win10
- 开源 免费 java CMS - FreeCMS-功能说明-操作日志
- Page 的生命周期学习小结
- 链路层 ---《TCP/IP协议》卷一
- BCB6.0里没有TCppWebBrowser
- 冗余云计算连接:保持组织运行
- creator qt 字体太小_qt ttf 字体太小的解决方法
- php cms 选择哪个好?
- php 二维数组根据键值合并二维数组_3分钟短文 | PHP 根据值移除数组元素,哪个方法最简单?...
- 刚才看到一篇文章,感觉不错,转载过来和大家分享:
- Shiro 支持三种方式的授权
- h5+js调取相机做取景框_iPhone 12 相机操作指南,用好了随手一拍就是大片!
- java 写文件缓存_使用java NIO及高速缓冲区写入文件过程解析
- python基础学习
- edius隐藏快捷键_EDIUS快捷键大全
- google license key格式不对
- 听说你还不会制作“GIF动图”,手把手包教会,这不就来了吗
- 用spark实现单词统计
- OUC_SE_Group04_Blog3
- javaweb mysql购物车_java web开发之实现购物车功能