[导读]关注、星标公众号,直达精彩内容来源: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
本站声明: 本文章由作者或相关机构授权发布,目的在于传递更多信息,并不代表本站赞同其观点,本站亦不保证或承诺内容真实性等。需要转载请联系该专栏作者,如若文章内容侵犯您的权益,请及时联系本站删除。
2023年10月18日,中国在第三届“一带一路”国际合作高峰论坛期间发布《全球人工智能治理倡议》,围绕人工智能发展、安全、治理三方面系统阐述了人工智能治理中国方案。
关键字:
人工智能
大模型
代码
我们看到这么多的安全问题,部分原因在于我们对待安全的方式:安全性通常被认为是事后考虑的问题,是在开发结束时才添加到设备上的东西。然而,复杂的系统,尤其是嵌入式系统,有一个很大的攻击面,这让攻击者有机可乘,能够在“盔甲”上...
关键字:
代码
嵌入式系统
软件漏洞
新富人群财务需求多元发展,投顾服务迎来新机遇 上海2023年9月20日 /美通社/ -- 2023年9月19日,上海交通大学上海高级金融学院(高金)与全球领先的金融服务机构嘉信理财(Charles Schwab)联合发...
关键字:
BSP
ADVANCED
INA
代码
北京2023年9月14日 /美通社/ -- 生物医药高科技公司诺诚健华(港交所代码:09969;上交所代码:688428)今日宣布,新型蛋白酪氨酸磷酸酶SHP2变构抑制剂ICP-189联用针对表皮生长因子受体(EGFR)...
关键字:
IC
HP
代码
ARMA
上海2023年9月1日 /美通社/ -- 2023上半年,安集科技(股票代码:688019)市场拓展规划成效显现,营业收入稳健增长。 全球半导体产业挑战持续存在的情形下,安集科技秉承发扬"克难攻坚,敢打硬...
关键字:
安集科技
BSP
代码
半导体材料
国际酒店运营商升级其在线支付功能 上海2023年8月28日 /美通社/ -- 加拿大金融科技公司Nuvei Corporation(以下简称“Nuvei”或“公司”)(纳斯达克代码:NVEI)(多伦多证券交易所代码:N...
关键字:
代码
IP
SE
纳斯达克
(全球TMT2023年8月24日讯)第三十届北京国际广播电影电视展览会(BIRTV2023)正在北京如火如荼地进行中。在展会上,成都索贝数码科技股份有限公司与深圳市洲明科技股份有限公司宣布签署战略合作协议,双方将携手布...
关键字:
模型
TV
编写
网络视频
2023年上半年收入7.459亿元 同比增长5.1% 毛利率水平上升 海外收入同比增长65.4% 香港2023年8月22日 /美通社/ -- 金邦达宝嘉控股有限公司及其附属公司(以下合称「金邦达」、「...
关键字:
数字化
代码
嵌入式软件
COM
我们经常对正在进行数字化转型的亚马逊云科技客户建议,将云迁移视为其数字化转型的一部分,数字化转型本身必须由业务成果驱动。其中治理计划的有效性决定了云迁移和数字化转型的成功与否。数字化转型中的云迁移总有结束的时候,但是如果...
关键字:
代码
数字化
云服务
广州及苏州生产基地产品均实现"出口"零突破 北京2023年8月21日 /美通社/ -- 百济神州(纳斯达克代码:BGNE;香港联交所代码:06160;上交所代码:688235)是一家全球性生物科技公...
关键字:
神州
代码
TI
PD
近年来,国内电子公司和芯片设计企业大举进攻汽车、医疗和工业等高可靠应用(mission-critical)领域,为自己找到了摆脱红海的新领域。但是高可靠应用多数都需要功能安全认证,在许多行业在诸如汽车、航空电子、医疗和工...
关键字:
代码
代码分析工具
北京2023年8月16日 /美通社/ -- 百奥赛图(北京)医药科技股份有限公司("百奥赛图",股票代码02315.HK)宣布"千鼠万抗TM"按计划实现重要里程碑进展,抗体业务板块...
关键字:
ICE
COM
GEN
代码
BlackBerry(黑莓)最大的尖端技术大会将于2023年10月17日在纽约举行 安大略省滑铁卢2023年8月3日 /美通社/ -- BlackBerry L...
关键字:
BLACKBERRY
BSP
COM
代码
近日,上海公安局普陀分局成功破获一起案件,并在程序员圈内引起了不小轰动。因为该案件涉及的金额高达1.5亿元,而这仅仅是在半年时间内的非法获利。要知道,这样的赚钱速度放在整个互联网界也都是相当炸裂的!
关键字:
代码
程序员
北京——2023年6月15日,亚马逊云科技在re:Inforce 2023全球大会上宣布,推出十多项安全新服务及功能,包括Amazon Verified Permissions正式可用、扩展Amazon Detectiv...
关键字:
机器学习
云服务
代码
IAR Embedded Workbench 9.40版本引入了与指针验证和分支目标识别(PACBTI)扩展的无缝兼容性,保护嵌入式应用程序免受各种安全攻击。
关键字:
代码
嵌入式应用程序
编译器
嵌入式系统在我们的日常生活中广泛存在,从消费类电子、医疗设备,到汽车,工业控制,航空航天等,它们的存在已经成为我们生活中不可分割的一部分。随着技术的不断进步和客户需求的增加,嵌入式系统和软件变得越来越复杂,同时产品的开发...
关键字:
代码
自动化工具
嵌入式系统
北京2023年3月10日 /美通社/ -- 生物医药高科技公司诺诚健华(上交所代码:688428;香港联交所代码:09969)今日宣布,公司自主研发的BCL2抑制剂ICP-248在中国完成首例受试者给药。 ICP-24...
关键字:
IC
BSP
代码
ARMA
妇科大咖云集 共话日间诊疗新模式 北京2023年3月7日 /美通社/ -- 为进一步推广由郎景和院士牵头,朱兰教授等我国多位著名妇科医学专家共同编著《日间宫腔镜手术中心设置及管理流程中国专家共识》,普及日间宫腔镜诊疗理...
关键字:
东风
内窥镜
编写
调试
以全新面貌,筑梦多品牌协同发展未来 上海2023年2月28日 /美通社/ -- 近日,骊住水科技集团携旗下德国高仪、美国美标、日本伊奈和骊住厨房共同喜迁新址,正式入驻上海浦东新区前滩国际广场,开启全新篇章。本次乔迁实现...
关键字:
数字化
MOHAN
代码
供应链