说三道四技术文摘-感悟人生的经典句子
说三道四 > 文档快照

避免代码注释的五大理由

HTML文档下载 WORD文档下载 PDF文档下载
代码注释的作用一直以来都被程序员们广泛讨论。很多人认为注释不是必要的,写注释那是因为代码可读性太差了。原文作者Paulo Ortins发表了博文《避免代码注释的五大理由》,一起来看下。

代码注释的作用一直以来都被程序员们广泛讨论。很多人认为注释不是必要的,写注释那是因为代码可读性太差了。原文作者Paulo Ortins发表了博文《5 reasons to avoid code comments》,以下为译文:


通常,我们阅读软件比编写软件花费的时间要更多。虽然我从未见过任何科学研究能够证明这一点,但是在软件领域,它就好比一个教条或者信念如此的根深蒂固。正因为编写软件要比阅读软件要容易,因此代码的可读性而显得尤为重要。程序员可以通过一些技术来实现它,其中一点就包括代码注释。

关于代码注释的文章,网络上有很多讨论。我们应该使用注释来解释代码吗?还是应该注重编写表达式代码而无需阅读注释?Joe Kunk曾发表过一篇文章《To Comment or Not to Comment》其中有段内容是说所谓的好代码是指我们应该避免注释,因为注释通常是用来解释/隐藏恶意代码。

下面就来讨论下避免写代码注释的五大理由:

1. 程序员更加倾向于鼓励”坏“代码。

有一种说法,有代码注释的就是好代码,因此,程序员经常在代码边上写注释,使其看起来更加出色。如果我们把代码注释当做一种信号,那么也许我们正在编写坏代码。每当我们写注释时应该思考如何使代码看清来更加洁净。

2. 花费更多时间来编写和维护

如果注释没有跟随代码的变化而变化,即使是正确的注释也没有用。注释通常作为代码的第二个版本。当为某个函数写注释时我们需要不断的重复自己,这就违反了DRY(Don’t Repeat Yourself) 原则。花费时间来增加复杂性,软件需求改变了,代码也随之跟着变化。如果我们写注释,这就意味着必须去维护注释。因此,除非是很必须要,否则我们应该拒绝在注释上花费双倍时间,相反我们可以利用这些时间来提高代码的质量或开发新的特性。

3. 注释不是测试/验证

修改代码可以依赖工具,比如使用编译器、IDEs及单元测试;而注释却不能。注释没有这些工具,你无法依赖工具或者单元测试在正确的地方或者过期后来确保它们的正确性。一旦你写了注释,没有测试模块来验证它的正确性,一旦这个注释失败了,那么它就永远的失败了。

4. 注释没有代码文档可靠

通常,注释过期后,它们往往与代码失去了连接性。程序员阅读这些注释或许被“欺骗”了。即使不断的更新了代码注释,唯一了解的是这个代码应该是什么以及它的可读性。举个例子,如果老本问我们如果项目发生了更改,我们从哪能看出?是代码还是注释?——答案当然是代码。

5. 代码注释风格填补了屏幕空间

采用标准化的注释尤为重要,某些注释标准(如同下面)使用了很多行,这就要求你尽可能多的阅读更多代码。

/*** * @param title The title of the CD* @param author The author of the CD* @param tracks The number of tracks on the CD* @param durationInMinutes The duration of the CD in minutes*/public void addCD(String title, String author, int tracks, int durationInMinutes) {CD cd = new CD();cd.title = title;cd.author = author;cd.tracks = tracks;cd.duration = duration;cdList.add(cd);}

PS:本文所说的“避免代码注释",并不是说就不写代码注释,而是尽量避免去写代码注释,假如你认为值得也可以这么做。

此前,我们还发表过《五种应该避免的代码注释》以及《10个最“优秀”的代码注释》,不妨移步去看下。

原文出自:Pauloortins

极路由加入海尔U+联盟 可跨品牌控制多款家居设备 《近匠》Amaze UI:做最懂中国程序员的开源HTML5框架 Testin CTO徐琨:要做测试领域的阿里云! TIOBE 2015年2月编程语言排行榜:JavaScript排名达历史最高点 机智云发布第二代GoKit开发板,兼容Arduino与Intel Edison 计算机视觉,让冰冷的机器看懂这个多彩的世界 昔日学霸反哺教育 打造教育领域今日头条 第三方DevOps实践报告发布 84%中国企业预将受益 《程序员必读之软件架构》作者Simon Brown:架构师与程序员的区别 Xcode 6.3 Beta发布,Swift 1.2带来哪些新变化? 应用生与死:移动测试究竟该怎么搞? Chrome将跟SPDY说再见,拥抱HTTP/2 ImageNet挑战赛中超越人类的计算机视觉系统 微软发布首款Android可穿戴设备人工智能产品 红包大战!双11过后,微信支付宝的又一个营销游戏 O2O大潮来袭,洗牌将至? 谈谈UI架构设计的演化 Node.js 开源基金会成立,Joyent让出领导权 LinkedIn分布式实时性能跟踪与效率优化实例 DIY机器人不是事!软硬两不误的开发平台RoboCORE 详解OS X和iOS图像处理框架Core Image 快的打车联合创始人兼技术副总裁闻诚:CTO要有“334”能力 阿里巴巴正式加入W3C,成为W3C会员 在Swift中,如何像Objective-C定义可选接口? DARPA:4年内推出具备触觉的机械手 Silver:用Swift编写iOS、Android和.NET应用 Swift没有异常处理,遇到功能性错误怎么办? 基于Python的测试驱动开发实战 不能守株待兔!移动互联网时代:产品找用户 淘汰传统屏幕,虚拟现实新纪元何时开启? 《近匠》SENSORO CTO赵东炜:解密iBeacon生态 有关时间限制 ie问题有没有碰到过 TADOTable+TDBGridEH+TDataSource中编辑一有关键字的表时,怎样做到避免在输入相同的关键字时的出错? IE经常自动关闭是什么原因 菜鸟请教 UlraEdit? 四舍五入的函数是什么?? 帮帮忙!!!我编译出这问题?? 请问:发现病毒:生成folder.htt,还有后缀都是htt的其他文件,用kv3000杀,提示kbs\kj,请问是什么病毒,怎么杀毒(急)? ie问题有没有碰到过 打开adsl的猫机器能自己启动为什么? 神洲数码怎样? linux中如何得到某个网络设备的ip地址? 请教ADO的Recordset对象的Delete的问题 请问jbuilder的参考书,哪本比较好?市面好像种类比较少 请问怎样获得临时表的记录? @@@@@@@@@@如何使我的折线图随着时间移动@@@@@@@@@@ 菜鸟问:各位大哥看c++ primer的时候是用什么编译器? 神洲数码怎样? jsp如何将web页面的String型转换为long型? 极容易的问题 ,先来先得! 大虾,救命啊!!!!!! jsp如何将web页面的String型转换为long型? ★★★帮忙翻译一句话!谢谢★★★ **冗余醒目**《如何在输入的时候减小冗余》**冗余醒目** 倡议书:维护您的网络权益 [100分,两日内结]怎样在jsp中得到我的数据 两个菜鸟问题,送分拉 线程与消息??? c、odbc、嵌入式sql的关系? 简单的重载问题! 用<input type="fiel" name="test">时,怎样判断输进去的文件是硬盘上实际存在的? 请问哪里有eclipse 下载? FINDING SOMEBODY! 显示器不亮,请帮忙,解决给100分 写在3.15黎明的前夕 **冗余醒目**《如何在输入的时候减小冗余》**冗余醒目** 各位,CSDN的论坛都是用些什么工具开发的?? 请问个位大虾,我的程序为什么不能执行(TC++3.0) 在VC中怎么调用IE来显示一个页面? 怎样在新开的页面给已开的页面上的一个TextBox插入新的字符串 [转贴]网络版权问题 **冗余醒目**《如何在输入的时候减小冗余》**冗余醒目** 用purify测试过的release版本怎么在别人的计算机上运行有问题? 如果用asp连接mysql,请问连接字符串是什么? 我要做一个在小型的对等网上运行的数据库软件,用什么方法好点? 如果用asp连接mysql,请问连接字符串是什么? 请高手帮我解答一个关于在ASP中调用存储过程的问题? 怎么输入繁体字? 足彩-03010期:1033031110310 请教高手在DELPHI里怎样实现把一个文件存储到ORACLE上, 然后又如何调出来使用?? 二氧化碳含量最高的是 A 呼出气体 B组织细胞 什么东西能导电? 肺内气体的交换的原理是:气体向低浓度处扩散,直至两边气体平衡,那为什么与血液进行了气体交换后二氧化碳多于氧气,应该是一半的一半嘛? 呼出的气体中氧气含量. 在火车厢里跳起来会落在原地还是在后面 效率高得机械,功率一定大是对的吗,做工快的机械呢 读狐狸和狗 有感 400~500字狐狸钻进羊群,抱起一只正在吃奶羔羊,假意抚爱他.牧羊犬见了,问道“你这是干什么?”狐狸说“我照料他,逗他玩”牧羊犬说“你不立刻放下他,我就让你尝尝什么是狼 地球是圆的,而且在自西向东转动着,为什么人跳起来还会落到原地、? 忙碌的近义词,连续的反义词,谨慎的近义词 二氧化碳验满将燃着的小木条放到收集好二氧化碳的集气瓶的瓶口 为什么小木条没有熄灭 人在高速行驶的车上跳起来人还会落在原地吗? 机油泵的油的浓度与开启压力有什么关系转子组件机油泵用的 油的浓度和他的开启压力的高低有关系吗 还有流量 想要验满氧气应怎样做是将带火星木条放入集气瓶口还是将带火星木条接近集气瓶口 在你身边,若有一束电子从上向下运动,在地球磁场的作用下,他将?向西偏转 这道题主要问题是判别地磁场的方向敢问地磁场到底是怎么分布的?有图么 二氧化硫与压力的关系,也就是压力怎样影响二氧化硫的浓度 形容小区环境不错的句子段落(最好有关于环保的) 阿拉斯加的海洋哺乳动物数量减少还是增加了呢? 曼富图的云台能不能装在百诺的三脚架上面405云台能不能装在百诺的4系的脚架上面?我很好奇 形容打架的句子或段落 化学:四氯化碳之间也是共价键相连啊,为何是分子晶体而不是原子晶体?原子晶体的具体概念? 二氧化硅 金刚石有无分子间作用力?什么样的物质的微粒存在分子间作用力?谢 一个密封的杯子,不断向外抽气,里面空气的密度变化吗? 在匀速行驶的火车上,我们竖直向上用力地跳起来,落下来后为什么还会站在原地? 高中物理竞赛重点考点 季羡林的文章 一条老狗 读后感 火车提速原理近十年来,铁道部先后6次实行火车大提速.为了适应提速的要求,则()A 机车的额定功率可以保持不变 B 机车的额定功率必须减小C 铁路转弯处的路基坡度应加大 D 铁路转弯处的 如何将云台安装到三脚架上?曼富图808RC4云台+百诺三脚架.安装起来有点费劲,求指导, 生活中哪些是导电海绵(泡沫)?要常见的,到点效果好的, 站在火车上,跳起来,还在原来的地方吗我们的意见不统一, 二氧化硅和金刚石用化合键构成的物质中为什么没有分子间作用力 谁能告诉我包装泡沫导电吗?我不小心把一粒白色的包装用的泡沫掉进液晶显示器中去了,请问这样会造成短路吗?如果不会短路,那么对显示器的使用有什么影响. C为线段AB的中点,D为AB上的一点,E为AD的中点,且AD=6,EC=7.求DC,AB的长. 二氧化硅中不存在分子,为什么呢 什么叫导电海绵 C为线段AB的中点,D为线段AB上一点,E为线段AD的中点,且AD=6cm,EC=7cm.求线段DC,AB的长 为什么灭火器过期了就不能用了?如果用了能怎样? 塑料泡沫是否导电 电势梯度,电势,电场强度哪两个是相等的物理量 为什么沿磁场方向导体不受力的作用?公式知道,有个夹角的关系.可是,能不能不通过公式说明?我觉得即使平行,会不会沿着导线方向有个拉力什么的呢?怎么会不受力呢? 高中物理竞赛需要培养哪些思维能力?尽量完整些,谢谢. 什么东西不会导电 螺线管内部均强磁场 不受力的作用吗 高中的物理竞赛要怎么学才能考出好成绩? 写反义词:甜蜜 为什么空气中氧气的含量是恒定的? 海豚真的救过人类吗? 甜蜜的反义词是? 同体积的冷水和热水分子间的平均距离谁的大? 高中离子方程式总结谁能帮我把高中所以离子方程式总结下 所有不是所以不好意思 C是线段AB的中点,D是线段CA上的一点,E为线段AD的中点,如果BD=6,求EC的长. 干净的反义词是什么 高一化学离子方程式的总结 中华鲟是海洋动物,还是淡水生物 "干净"的反义词是什么? 高一化学离子方程式总结 C是线段AB的中点,D是线段CA上的一点 ,E为线段AD的中点.如果BD=6 求线段EC的长. 干净反义词 呼出气体含量最多是什么我个人认为第一是氮气 第二是氧气 第三才是二氧化碳 我问过全班同学 包括化学老师 他们都说二氧化碳最多 真的气的我嘴都歪了 有Q可能啊 我还专门上网查了查 结 C是线段AB的中点 D是线段CA上的一点 E为线段AD的中点 如果BD=6 求线段EC的长. 二维的扩散方程是什么啊?浓度与位置的关系? 伊拉克北部自杀式炸弹袭击致数十人伤亡德媒:美国监听德国总理手机 奥巴马知德媒称奥巴马默许窃听默克尔手机河北首条省内低成本航线通航 机票最低综述:中国西藏文化周藏学家交流活动受中国房地产商在澳投资“风生水起”浙商二代展开青春对话 宗馥莉称不努力调查指:中国20年“农转非”比例仅增第九届两岸经贸文化论坛在广西南宁闭幕浙江力推“国民共进” 促“国字号”“长三角“绿色制药”协同创新中心:让百教师因婆婆不拆迁调岗至拆迁部 称曾被跨国公司巨头和学者会聚上海探讨城市“马尼拉市长最快下月底赴香港道歉 或赔上海自贸区满月在即 创新运行框架基本韩正:上海自贸区将适时引入第三方评估安倍再次表示推进探讨行使集体自卫权阿根廷学者认为克里斯蒂娜连任机会渺茫学者称克里斯蒂娜连任机会渺茫 应加强阿根廷学者认为克里斯蒂娜连任机会渺茫中央气象台发霾黄色预警 京津等局地或公车私用不对 但我没违法冰火两重天影讯(23日)还有可能是“宰人的黑车主”美驻日大使狠批“海豚湾”杀戮115万人忙销户南非发现超大蓝钻一群小年轻“团购”摆摊老人报刊滑板猫的幸福生活江苏:男子双手被轧断 医生将其右手植陆运涛的死成全了邵逸夫霸主之梦晶方科技今日恢复发行“卖糖翁”苦等失主……南京市长谈治霾:市长和区长都要签订责世纪华通募资18亿“牛散”转型:不赌重组 改打新股年堵 商贸区车流增加15%今日看点增加徐州、南通方向运能怕麻烦儿女,不少老人养老院过年“学问”大
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘