[导读]关注、星标公众号,直达精彩内容来源:CSDN(ID:CSDNnews)作者:EllenSpertus| 译者:王雪迎 虽然有很多资源可以帮助程序员编写更好的代码,比如书籍或静态分析器,但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易,但衡量注释的质量却很...
虽然有很多资源可以帮助程序员编写更好的代码,比如书籍或静态分析器,但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易,但衡量注释的质量却很难,而且两者并不一定相关。差的注释比根本不写注释更糟糕。这里有一些规则可以帮助你实现一种折中的方法。
麻省理工学院的著名教授Hal Abelson曾说过:“程序必须写给人们阅读,而只是附带地让机器执行。”虽然他可能故意低估了运行代码的重要性,但却注意到了程序有两种截然不同的受众。编译器和解释器会忽略注释,找出同等容易理解的所有语法正确的程序。而人类读者则完全不同。我们发现有些程序比其它的更难理解,此时就会通过查看注释来帮助我们理解这些程序。
虽然有很多资源可以帮助程序员编写更好的代码,比如书籍或静态分析器,但是很少有资源可被用于编写更好的注释。虽然度量一个程序中的注释数量很容易,但衡量注释的质量却很难,而且两者并不一定相关。差的注释比根本不写注释更糟糕。正如Peter Vogel所述:
-
编写并维护注释是一项开销。
-
编译器不会检查注释,因此无法确定注释是否正确。
-
另一方面,你可以保证计算机完全按照你的代码所示运行。
所有这些观点都是正确的,但如果走到另一个极端,即从不写注释,那将是一个错误。这里有一些规则可以帮助你实现一种折中的方法:
-
规则1:注释不应与代码重复。
-
规则2:好的注释不能成为代码不清晰的借口。
-
规则3:如果无法写出一个清晰的注释,代码可能有问题。
-
规则4:注释应该消除混乱,而不是引起混乱。
-
规则5:在注释中解释不规范的代码。
-
规则6:提供复制代码的原始出处链接。
-
规则7:在可能提供帮助的地方引入指向外部参考的链接。
-
规则8:在修复bug时添加注释。
-
规则9:使用注释来标记未完成的实现。
本文其余部分将逐条解释这些规则,提供示例并说明如何以及何时应用它们。
01
规则1:注释不应与代码重复
许多初级程序员会写太多注释,因为他们接受了入门指导老师的培训。我曾见过计算机科学系的高年级学生为每对大括号加上一条注释,以表示该块结束:
if (x > 3) { …} // if 我也听说过老师要求学生对每一行代码进行注释。虽然这对极为初级者来说可能是一个合理的策略,但这样的注释就像是训练轮,在大孩子骑车时应该去掉。
不添加任何信息的注释具有负价值,因为它们:
一个典型的坏示例为:
i = i 1; // Add one to i 它不添加任何信息,并切产生维护成本。
每一行代码都需要注释的策略在Reddit上都受到了相当的嘲笑:
// create a for loop // <-- commentfor // start for loop( // round bracket // newlineint // type for declarationi // name for declaration= // assignment operator for declaration0 // start value for i
02
规则2:好的注释不能成为代码不清晰的借口
注释的另一个误用是提供本应包含在代码中的信息。一个简单的例子是,有人用一个字母命名一个变量,然后添加一个描述其用途的注释:
private static Node getBestChildNode(Node node) { Node n; // best child node candidate for (Node node: node.getChildren()) { // update n if the current state is better if (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在编程风格要素一书中所写,“不要注释糟糕的代码 — 重写它。”
03
规则3:如果无法写出一个清晰的注释,代码可能有问题
Unix源代码中最臭名昭著的注释是“你不希望理解它”,它出现在一些恐怖的上下文切换代码之前。Dennis Ritchie后来解释说这是故意为之:“本意是想表达‘这不会出现在考试中’,而不是作为一种厚颜无耻的挑战。”不幸的是,结果发现他与合作者Ken Thompson自己也理解不了,后来不得不重写。
这让人想起了Kernighan定律:
调试在一开始就比编写程序困难一倍。因此,按照定义,如果你的代码写得非常巧妙,那么你就没有足够的能力来调试它。
警告读者远离你的代码就像打开汽车的危险警示灯:承认你正在做知法犯法的事情。相反,把代码重写成你充分理解的东西,或者更进一步,直截了当地进行解释。
04
规则4:注释应该消除混乱,而不是引起混乱
如果没有Steven Levy的 黑客:计算机革命的英雄 中的这个故事,任何关于负面注释的讨论都是不完整的:
[Peter Samson]拒绝在源代码中添加注释来解释他在特定时间所做的事情,使其特别晦涩难懂。在一个分发良好的程序中,Samson继续编写了数百条汇编语言指令,其中只有一条包含1750数字的指令带有注释。注释是RIPJSB,人们绞尽脑汁研究它的含义,直到有人发现1750年是巴赫去世的那一年,而Samson写的注释是Rest In Peace Johann Sebastian Bach(安息吧,约翰·塞巴斯蒂安·巴赫)的缩写。
虽然我和别人一样欣赏一个好的黑客,但这种注释不可效仿。如果你的注释引起混乱而不是消除混乱,删除它。
05
规则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
本站声明: 本文章由作者或相关机构授权发布,目的在于传递更多信息,并不代表本站赞同其观点,本站亦不保证或承诺内容真实性等。需要转载请联系该专栏作者,如若文章内容侵犯您的权益,请及时联系本站删除。
9月2日消息,不造车的华为或将催生出更大的独角兽公司,随着阿维塔和赛力斯的入局,华为引望愈发显得引人瞩目。
关键字:
阿维塔
塞力斯
华为
加利福尼亚州圣克拉拉县2024年8月30日 /美通社/ -- 数字化转型技术解决方案公司Trianz今天宣布,该公司与Amazon Web Services (AWS)签订了...
关键字:
AWS
AN
BSP
数字化
伦敦2024年8月29日 /美通社/ -- 英国汽车技术公司SODA.Auto推出其旗舰产品SODA V,这是全球首款涵盖汽车工程师从创意到认证的所有需求的工具,可用于创建软件定义汽车。 SODA V工具的开发耗时1.5...
关键字:
汽车
人工智能
智能驱动
BSP
北京2024年8月28日 /美通社/ -- 越来越多用户希望企业业务能7×24不间断运行,同时企业却面临越来越多业务中断的风险,如企业系统复杂性的增加,频繁的功能更新和发布等。如何确保业务连续性,提升韧性,成...
关键字:
亚马逊
解密
控制平面
BSP
8月30日消息,据媒体报道,腾讯和网易近期正在缩减他们对日本游戏市场的投资。
关键字:
腾讯
编码器
CPU
8月28日消息,今天上午,2024中国国际大数据产业博览会开幕式在贵阳举行,华为董事、质量流程IT总裁陶景文发表了演讲。
关键字:
华为
12nm
EDA
半导体
8月28日消息,在2024中国国际大数据产业博览会上,华为常务董事、华为云CEO张平安发表演讲称,数字世界的话语权最终是由生态的繁荣决定的。
关键字:
华为
12nm
手机
卫星通信
要点: 有效应对环境变化,经营业绩稳中有升 落实提质增效举措,毛利润率延续升势 战略布局成效显著,战新业务引领增长 以科技创新为引领,提升企业核心竞争力 坚持高质量发展策略,塑强核心竞争优势...
关键字:
通信
BSP
电信运营商
数字经济
北京2024年8月27日 /美通社/ -- 8月21日,由中央广播电视总台与中国电影电视技术学会联合牵头组建的NVI技术创新联盟在BIRTV2024超高清全产业链发展研讨会上宣布正式成立。 活动现场 NVI技术创新联...
关键字:
VI
传输协议
音频
BSP
北京2024年8月27日 /美通社/ -- 在8月23日举办的2024年长三角生态绿色一体化发展示范区联合招商会上,软通动力信息技术(集团)股份有限公司(以下简称"软通动力")与长三角投资(上海)有限...
关键字:
BSP
信息技术
山海路引 岚悦新程 三亚2024年8月27日 /美通社/ -- 近日,海南地区六家凯悦系酒店与中国高端新能源车企岚图汽车(VOYAH)正式达成战略合作协议。这一合作标志着两大品牌在高端出行体验和环保理念上的深度融合,将...
关键字:
新能源
BSP
PLAYER
ASIA
上海2024年8月28日 /美通社/ -- 8月26日至8月28日,AHN LAN安岚与股神巴菲特的孙女妮可•巴菲特共同开启了一场自然和艺术的疗愈之旅。 妮可·巴菲特在疗愈之旅活动现场合影 ...
关键字:
MIDDOT
BSP
LAN
SPI
8月29日消息,近日,华为董事、质量流程IT总裁陶景文在中国国际大数据产业博览会开幕式上表示,中国科技企业不应怕美国对其封锁。
关键字:
华为
12nm
EDA
半导体
上海2024年8月26日 /美通社/ -- 近日,全球领先的消费者研究与零售监测公司尼尔森IQ(NielsenIQ)迎来进入中国市场四十周年的重要里程碑,正式翻开在华发展新篇章。自改革开放以来,中国市场不断展现出前所未有...
关键字:
BSP
NI
SE
TRACE
上海2024年8月26日 /美通社/ -- 第二十二届跨盈年度B2B营销高管峰会(CC2025)将于2025年1月15-17日在上海举办,本次峰会早鸟票注册通道开启,截止时间10月11日。 了解更多会议信息:cc.co...
关键字:
BSP
COM
AI
INDEX
上海2024年8月26日 /美通社/ -- 今日,高端全合成润滑油品牌美孚1号携手品牌体验官周冠宇,开启全新旅程,助力广大车主通过驾驶去探索更广阔的世界。在全新发布的品牌视频中,周冠宇及不同背景的消费者表达了对驾驶的热爱...
关键字:
BSP
汽车制造
此次发布标志着Cision首次为亚太市场量身定制全方位的媒体监测服务。 芝加哥2024年8月27日 /美通社/ -- 消费者和媒体情报、互动及传播解决方案的全球领导者Cis...
关键字:
CIS
IO
SI
BSP
上海2024年8月27日 /美通社/ -- 近来,具有强大学习、理解和多模态处理能力的大模型迅猛发展,正在给人类的生产、生活带来革命性的变化。在这一变革浪潮中,物联网成为了大模型技术发挥作用的重要阵地。 作为全球领先的...
关键字:
模型
移远通信
BSP
高通
北京2024年8月27日 /美通社/ -- 高途教育科技公司(纽约证券交易所股票代码:GOTU)("高途"或"公司"),一家技术驱动的在线直播大班培训机构,今日发布截至2024年6月30日第二季度未经审计财务报告。 2...
关键字:
BSP
电话会议
COM
TE
8月26日消息,华为公司最近正式启动了“华为AI百校计划”,向国内高校提供基于昇腾云服务的AI计算资源。
关键字:
华为
12nm
EDA
半导体