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

避免代码注释的五大理由

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

找虐新方向!TinyScreen显示屏打造最小游戏机 精彩继续 MDCC2014首次推出技术训练营 复制器官哪家强?3D生物打印找PrintAlive 电信开放平台应用内计费SDK 助力App小额快捷支付 专心做设计!开源跨平台应用开发框架Appverse Mobile 无线盛宴尽在阿里百川开放大会 医学界的Instagram:加拿大重症监护医生开发照片分享应用 2014中国移动开发者大调查第二批获奖名单揭晓 基于OpenStack的私有云开发部署实践 亚马逊云平台的迁移过程 【干货】微信企业号开发资源集锦 CSS生日快乐:CSS之父Håkon Wium Lie访谈录 好友近2000万,绑定银行卡过千万,日会话近百万,招商服务号成功之道 一名程序员十年技术之路的思考与感悟 聚焦企业号、服务号典型案例 微信开发者大会深圳站正式开启 Objective-C之父Brad Cox访谈:我的编程之路 【先锋】完成B轮融资的TalkingData新商业模式:平台理念+跨界分析+技术开源 1/10计算资源,1/3耗时,Spark颠覆MapReduce保持的排序记录 Cookie已死,看Facebook、Google、Apple如何追踪用户 Clay.io基于AWS、Docker、HAProxy等的10X架构打造 经典服务/企业号案例来袭!2014微信开发者大会(深圳)亮点抢先看 移动应用云APICloud宣布完成A轮500万美金融资 从Apache Storm学到的经验教训 【CTO俱乐部走进天津】探讨如何成为技术团队管理者 不容错过!参加MDCC 2014移动开发者大会八个理由 你的钱被洗劫了么!APP安全问题来袭 10大最常见的数据库安全问题 南航微信服务号是如何炼成的? 超40项功能改进,虚幻引擎4.5正式发布! 【工具推荐】ER:可轻松构建一站式AJAX Web应用的开发框架 GraphLab:将大数据分析从理念运用到生产 请问到何处用蚂蚁下载photoshop6.01软件 在UPDATE的时候,如何返回受影响的记录个数?[Oracle8i] 请问各位谁能提供jpeg文件格式的中文说明??????????????????? [question]tmd的,有人惹我,怎么办 Windows CE, Windows NT Embedded等嵌入式操作系统和相关开发工具在上海如何购买??? mobile web application 里的softkey到底是怎么回事呀 [心情不好]砂粉阿 告他[我好伤心] 将2进制(16位)转为16进制(4位),怎么做? 请教!( VC.NET 里面怎么使用 MSFlexGrid ? JAVA的版本问题 哪儿有C#单独的编译器下载啊 ASP新手提问! 有谁知道在DELPHI中得到包括硬盘、多媒体、主板等信息? 请问小新,以及其它delphi高手一个简单问题,我从网上下载了一个报表控件,请问该如何使用? 一个关于TWinSocketStream的问题 scjp考题一道!!!!!!!! 小弟初学,如何从CString 转化到 int .thanks a lot. 我要学习数据结构,算法,离散数学..... [不爽阿]今天圣诞,有人惹我 关于临时表的共享问题? 是不是我的问题太难了,没有人回答? 请举例说明:接口是怎样实现多重继承的? 听说最近由于IT行业不景气,程序员的工资缩水了?是真的么? 这样写有什么不对?? delphi的dll库返回后调用程序出错!加了一行无关代码却正常!求教各位大狭! 塔尼包姆出了不1本计算机结构的书,还有1本MICROSOFT的 Microsoft Windows 用户界面开发 请问是否很好 Access初学者问一 再次请教一个sql排序问题,一定给分。 请问:程序中对WM_PAINT,WM_CTLCOLOR,WM_ERASEBKGND三个消息处理的顺序是怎样的? 这个月生意只有上个月的1/5,怎么回事? 我女朋友说最爱她的人不是我,这意味着什么? 工资里导入上月数据怎么实现 谁有复读王(fyfdw2001)的注册码? 经过一段时间的努力,我做出一套电话语音邮件系统,可以用电话和手机来收发EMAIL,有意者请与我联系 xuyaoliang@263.net 请救救我吧!有谁能告诉我中程的分数怎么查! 如何解决数据窗口显示照片(此照片在数据库的一个字段里)的问题? 请问如何获取硬盘和光驱的型号信息 谁有复读王(fyfdw2001)的注册码??????? n_up的问题。如何在另一列插入计算字段? 有没有深圳的mm,一起过圣诞好吗? far怎么用啊? 关于临时表的共享问题?? 请大家介绍一些学习C/C++的好网站,只要进者就给分。 "他妈的,又打歪了!" 我在作登录是出现了"runtime error"错误,详情见内 3台机子如何共享一个adsl上网?? 如何把一应用配置成一NT服务 出学的菜鸟提问 找回addin:资源编辑器 怎样开发阅读工具软件 四个数2836,4582,4970,6522被同一个自然数除,所得的余数都相同且不是0,则余数为() 英语翻译:“我只想知道你喜欢什么颜色,红色还是黄色.” 作文 我喜欢的颜色 硫是一种淡黄色晶体,t它的蒸汽有橙色,无色,红棕色三种,它们都是硫的单质,但分子中硫原子的个数不同可用Sx表示,对三种蒸汽的测定结果是(1)橙色蒸汽对氢气的密度是128,它的化学式是 (2 它的颜色是黄色和黑色的用英文翻译 皇帝的新装续写100字 皇帝的新装阅读皇帝的新装选段阅读题11.第4段的话和第五段的“他实在没穿什么衣服呀!”在叙述方式上有什么不同?刻画了人们怎样的心理?2.童话的结局让一个小孩说出了真话,是为了说明一 已知(x-2013)(x-2014)=m求(x-2013)的平方十(x-2014)的平方的值? 皇帝的新装续写700字 硫是一种淡黄色晶体,它的蒸汽有橙色,无色,红棕色三种,它们都是硫的单质,但分子中硫原子的个数不同,(1)橙色蒸汽对氢气的相对密度是128,则它的化学式____(3)红棕色蒸汽的质量是相同状 已知m,n是方程x²-2012x+2013=0的两根.求(m²-2013m+2014)(n²-2013n+2014)的值 皇帝的新装续写150字 硫是一种淡黄色晶体,它的蒸汽有橙色.硫是一种淡黄色晶体,它的蒸汽有橙色,无色,红棕色三种,它们都是硫的单质,但分子中硫原子的个数不同,可用Sx表示.对三种蒸汽测定结果是(1)橙色蒸汽 已知集合M={x|(x-2013)(x-2014)=0},N={x|x-2013>0.则M交N 计算1+2+3+...+2012+2013+2014+2013+2012+...+3+2+1 硫是一种淡黄色晶体,它的蒸气有橙无红棕色三种,分子中硫原子的个数不同,可用Sx表示,1橙色蒸气对氢气的相对密度是128则它的化学式是?2无色蒸气折算成标准状况下的密度是5.71g/L,3红色蒸气 皇帝的新装 阅读答案 急求啊 啊啊啊 写喜欢的一种颜色的作文 硫蒸气有橙色、无色、红棕色等颜色,他们都是硫的不同单质,所含硫原子的数目不同,可用Sx表示.对着三种蒸气的测定结果如下:1)橙色硫蒸气的质量是相同状时等体积空气的8.8倍,则它的化 皇帝的新装阅读答案皇帝的新装的皇帝、老大臣和官员为什么都不说真话?由此,你想到了什么?“任何不称职的,或者是愚蠢得不可救药的人,都看不见这衣服。”这句话在剧中起什么作用? 小学英语作文要求70个字重点写为什么喜欢这个颜色要英语的一个颜色:蓝色1 2楼的:写的不错,但我要的是英语的 一个自然数能被5整除又能被3整除,同时它被7除余数是4,这个数是什么? 求《皇帝的新装》阅读答案 皇帝的新装续写 200字 概括皇帝的新装在100字左右 7^2014-20×7^2013+2100×7^2012能被2009整除吗? 说明5^2013-3*5^2012+5^2011能被11整除 皇帝的新装概括300字概括 皇帝的新装故事梗概100字左右 ,快啊7的2014次方—20*7的2013次方+2100*7的2012次方能被2009整除吗?说明你的理由 皇帝的新装续写----300字左右急 为什么说三个数除以某个自然数所得余数相同,则其中任意两个数的差必能被这个自然数整除? 2014的三次方-2014能被2013整除吗?能被2015整除吗 皇帝的新装续写300字左右 如果a、b为自然数,并且a除以b余数为0,那么a能被b整除这是一道判断题请说对错理由 黄色 什么色配出绿色 用一个字概况《皇帝的新装》,并阐述理由,理由不少于300字2013年12月26日网上8:00 皇帝的新装 剧本改写要全,好的话追加50分! 绿色+黄色=什么颜色? 皇帝的新装续写300字, 红色加什么颜色等于黄色 黄色才是最美丽的颜色作文三百字 明黄色是什么色 任意4个整数中,必存在两个数,它们被3除的余数相同.你能说出其中的道理吗、 绿色多少种颜色,黄色多少种颜色,黑色多少种颜色,都哪些颜色 偏橙色的黄色和什么颜色是情侣色?如题……… 在任意4个整数中,必存在两个数,他们除以3所得的余数相同.你能说出其中的道理吗? 同步导学皇帝的新装答案 若2836.4582.6522.四个自然数都被同一个自然数相除所得余数相同且为两位数,那么除数与余数的和为( ) 任意四个整数中,必存在两个数,它们被3除的余数相同.你能说出其中的道理吗? 小学作文,我喜欢的颜色是白色代表什么? 如果2836、4582、5164、6522都被同一个自然数相除,所得余数相同且为两位数.求除数与所得余数之和.注意除是被除数除以除数! 红色加黄色等于什么颜色 作文:我喜欢的颜色 绿色哦(比较好写) 马上就需要!写的好,必有重谢! 若2836,4582,5146,6522四个自然数被一个自然数相除,所得余数相同且为两位数,除数和余数的和是多少?最好用简便方法, 求皇帝的新装阅读答案1.文章最终只有孩子说出了真话,“天真的声音”对我们有何启示?2.本文刻画了皇帝、官员和两个骗子.主要表现什么人物?表现他们的什么特点?本文具有什么样的社会意 我喜欢我自己 作文我喜欢我自己 一篇初中作文,至少600字语文作文 若2836,4582,5164,6522四个整数被同一自然数相除,所得余数相同,但不为零,求除数和余数各是多少? 皇帝的新装阅读题答案皇帝把他所有的衣服都脱下来.两个骗子装作一件一件地把他们刚才缝好的新衣服交给他.他们在他的腰周围那儿弄了一阵子,好像是系上一件什么东西似的.皇上在镜子面 皇帝的新装 写老大臣的几段1.老大臣为什么用“多么美的花纹”“多么美的色彩”来赞美布料,而不用别的语句?2.老大臣为什么不敢承认自己看不见布料这一事实?3.作者写老大臣的眼睛句子是
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn