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

避免代码注释的五大理由

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

艾普网络的OpenStack实践 移动周报:无需编程,分秒钟DIY一个移动网站 抢占先机:豌豆荚发布视频搜索产品 Cloud-Connect大会Day1:OCP与SwiftStack 云智能手机,将会很快威胁到Android和iPhone? 直接拿来用!超实用的Java数组技巧攻略 腾讯云俱乐部上海站:电商如何利用云提高核心竞争力 iOS开发者必备:六大图片、图标处理类工具 腾讯向搜狗注资4.48亿美金持股36.5% 推荐五款流行的JavaScript模板引擎 为何人人都将成为程序员?看32位美国顶尖精英的说法! MySQL再度失势:继维基百科之后,Google也迁移到了MariaDB Werner Vogels:亚马逊热爱艺术的CTO Jolla宣布Sailfish OS兼容Android手机硬件和应用 为什么项目估算偏差如此之大? Cloud Connect大会Day2:开源与云数据中心 CTO俱乐部第110期下午茶:利用麦肯锡7S模型构建管理框架 跨平台打造移动原生应用的10大武器 iOS与Android本地数据库新选择:使用Objective-C和Java编写 Cloud Connect大会day3:Intel的大数据与Metacloud私有云 农民也玩数据挖掘:基于物联网的高端种菜模式 前谷歌Android开源项目主管Queru加盟雅虎 Windows 8.1售价出来了!分别是119.99美元、199.99美元 对AngularJS进行性能调优的7个建议 为什么说UX设计师的黄金时代已来临? 豌豆荚:“应用内搜索”是打通移动互联网最具竞争力的入口 苹果发布会后的冷思考,64位芯片为开发者带来了什么? 中兴Geek评测:高性价比的英特尔处理器智能机 SAE的资源、安全隔离与Container 平板电脑悬了 Phablets或成为未来移动设备的主流 拿什么拯救你:黑莓今年将裁员4500人 数据库高手请进,值得一看 怎么从文本文件里取出其内容? 请大家帮忙看一下,关于Delphi的三层MIS开发 如何获得经典的C++/MFC方面的电子文档,中英都行,谢谢! 压缩中提到的文件头有什么作用 , 请问各位专家,在网页上如何制作视频点播?有几种方式! 我报了中程谁有历年的中程试卷? 我收到的信都是?号,怎么看???? VB中是否有移位操作符??是否有_能够得到数据类型宽度的函数? 哪里有core java的e版down啊? 有事好商量!请进! DLL编程错误,请高手指教一下!! 活见鬼,真气人....... 问一个trigger问题? 问一下:我的char*都用_T("asdfsafd")表示了,资源也没任何问题,可有时候运行程序显示乱码 在论坛里,发一个帖子新开一个窗口,当发完后让原来那个窗口刷新一下 我的机子到底怎么回事???? 我试试.. CListCtrl中如何选定整个一行? 来到济南天气太热,特来送分 ★★★★★ 见于现在伪ID和盗用密码的现象十分嚣张,我提议…… ★★★★★ 请教各位,我用vb6.0访问ms sql7.0数据库,为什么有时出现,“过期,数据已超时?” 请问COM和DLL有什么区别和联系?(30分) 关于侯老师 win95-a-developers-guide 一书的源配书... ISAPI中不能存取ASP中的Session、Application变量?高手你老人家在哪里? 大家来看看这些招聘题目合不合适 提一个网页制作的问题哈,大家不要扔西红市啊,网叶制作可是程序员的基本技能之一 activeskin里的skinbuilder有谁用过???来讨论吧 我在msdn上看到vb中的字符串有两种:定长字符串和变长字符串。请问如何分别声明这两种类型? 怎样在ADO中引用已打开的recordset的某一字段值,请给几个例,谢谢了! seedundersnow and holyfire help me!about 8253! 谁有cute ftp 4.2.6 beta的注册码 请问如何把页面查询到的记录导入到Excel中呢? 有用过TAdvStringGrid的吗?OnGetEditorType( )为何不被调用? 请教高手如何用Xsl编制函数控制Xml??急急 哪位给一个MD5的例子!谢谢了 长春的李延生来领分 求救:一个VC中多线程的问题 提个问题,原来对VC尤其是界面和C++语法这一块比较熟,现在由于公司需要转C++BUILDER,难不难,需要熟悉哪些 [总300分,会继续加分]哪位大哥用编程实现过创建SQL Server的DTS package并且run the package的全过程[急] 能不能使用html 压缩中提到的文件头有什么作用 , 保含哪些信息 菜鸟问题1 提一个网页制作的问题哈,大家不要扔西红市啊,网叶制作可是程序员的基本技能之一。。。。。。。 关于:import java.util.StringTokenizer; 问题! 如何实现在某特定时间(如每月1号,或7天后)执行特定asp程序? 在开发工具中如:(vc,jsp)中如何得到oracle中自定义函数的返回值 当form被移动的时候会相应什么事件的? 关于使用mscomm32.ocx中的一些问题 类似股票信息显示系统的问题(图形显示) 强烈抗议:无怨无仇,为什么冒用我的ID 写一些乱七八糟的东西????? 一个圆柱形蓄水池底直径是10米,池深1米这个蓄水池的容积是多少立方米 简便计算:0.75x16+3/4x5一75% 2.7x0.6+4/5x2.7-2.7x2/简便计算:0.75x16+3/4x5一75% 2.7x0.6+4/5x2.7-2.7x2/5 95x38+62÷1/95 {5/6-(2/5+1/3)}x5/7分数啊.急 一个圆柱形蓄水池,底面直径是10米,池深5米.这个水池的占地面积是多少平方分米?(2)在四周和底面抹上水泥,水泥的面积是多少平方分米?(3)蓄水池的最大容积是多少立方分米? 2²+4²+6²+···+50² 编写一个程序,计算x-1/2*x3/4+1/2*3/4*x5/6-1/2*3/4*5/6*x7/8+.的近似值直到最后一项的绝对值小于eps 用c语言编~ 一个长方体蓄水池长8m,宽4m,深3m.这个蓄水池占地面积是多少平方米?在池底和四周抹水泥,抹水泥的面积多少?蓄水多少立方米? 2²+4²+6²+.+50²等于多少等于多少赶时间 (X一5/6)X5/6=25. 校要建一个底面周长12.56M,高3M的圆柱形蓄水池,这个水池的占地面积是多少 抹水泥的面积有多少平方M? 计算:1²-2²+3²-4²+5²-6²+...+49²-50²急、在线等 解方程,(x+5.5)X5=120怎么算用T等式 某农场挖了一个圆柱型蓄水池,底面直径是3m,高是8m 1要在这个蓄水池的周围和底面上抹上一层水泥,抹水泥的面积是多少平方米?2在这个蓄水池内装满水可以装多少立方米的水 求(a-2)²-6(2-a)的值 其中a=-2 计算(一5)一(一5)x5分之一x(一4) 一个圆柱形蓄水池,底面半径2m,深3m,在池底和四周抹上水泥.如果每平方米用水泥20千克,水泥要用多少千克 (1).(a-b)²-(a-b)-2 (2).(a+b)²+(a+b)-6 已知sinθ,cosθ是关于x的方程x^2-ax+a=o的两个根 θ求1.sin^3(θ)+cos^3(θ)的值2.tanθ+1/tanθ的值 一个长方体水池长5分米宽4分米深3分米,水面离池口4厘米放一块棱长2.1分米的正主体石块水会溢出多少毫升 a-b=2,a²+b²=6,则ab=? 已知关于x的方程2x^2-〔(根号3)+1〕x+m=0的两根为 sin θ,cos θ ,θ∈(0,2π)1.sinθ/(1-cotθ)+cosθ/(1-tanθ)的值2.m的值3.方程的两根及此时θ的值 一个长方体水池,长6米,宽5米,深0.68米,水面距池口18厘米,这个水池里有多少立方米的水? 若a+b=6.ab=2.则a²+b²=()(a-b)²=() 已知 θ∈【0,2π】sinθ,cosθ是关于X的方程X方-KX+K+1=0的根,求角θ 一个长方体水池长5分米,宽4分米深3分米,水面离池口4厘米放一块棱长2.1分米的正主体石块这时水会溢出吗? ①a(a-1)-2=0②a(a²-1)-6≠0.求a 已知关于x的方程2x^2-(√3+1)x+m=0的两个实数根为sinθ和cosθ,θ属于(0,2π)求方程的根及θ的值 某化工厂挖了一个蓄水池,能蓄水1080吨.这个蓄水池长24米,宽8米,深是多少米(每立方米的水重1吨 打一成语 一 7/8 1、2、5 二四六八十 0000 40÷6 1% 7÷2 1000²=100×100×100 设x1、x2 是一元二次方程x2+4x-3=0的两个根,2x1(x22+5x2-3)+a =2,  则a = .设x1、x2是一元一次方程X平方+4x-3=0的两根,2x1(x2的平方+5x2-3)+a=2,则a=我知道怎么算了 a=8 心情好啊 一个长18米的长方体蓄水池,现蓄水720吨,池内水深4米,这个水池宽多少米?(1立方米的水重1吨) 打一成语 (1)一 (6)0000 (7)40÷6 (8)1% (9)7÷2 (10)1000²=100×100×100二四六八十÷7 设X1、X2是一元二次方程 X - 4X - 3 = 0 的两个根,2X1(X2+5X2-3)+a=2,则a=___ 一个长方体的蓄水池从里面量长7.6米,宽5米如果池中以蓄水22.8吨池中水深多少米每立方米水重1吨列方程解答一个长方体的蓄水池从里面量长7.6米,宽5米。如果池中以蓄水22.8吨池中水深多少 (1²+3²+5²+……+99²)-(2²+4²+6²+……+100²) 设x1,x2是一元二次方程x²+4x-3=0的两个根,2x1(x2²+5x2-3)+a=2,则a= 一个圆柱形蓄水池,底面半径4米,深5米(1)这个水池能蓄水多少吨?(每立方米水重一吨)若在这个水池的侧面和池底抹上一层水泥,抹水泥的面积多大? 1-2²+3²-4²+5²-6²+……+99²-100² 关于x的实系数一元二次方程x²+ax+2b=0的两个实数根分别位于区间(0,1)(1,2)则b-2/a-1的取值范围是 一个圆柱形水池,底面半径3米.5米.这个水池最多可盛水多少吨?(1立方米的水重1吨) 1²-2²+3²-4²+5²-6²+····+99²-100²=急求,好的加分 关于x的一元二次方程5x²-ax-1=0有两个不同的实根 一个位于区间(-1,1)另一个(1,2关于x的一元二次方程5x²-ax-1=0有两个不同的实根 一个位于区间(-1,1)另一个(1,2) 则实数a的取值范围 求 某动物园有一个圆柱形状的水池内直径10米深0.6米.如果放水后水面离池口0.1米,有水多少吨(1立方米水重1 7.5X2.7+1.9X2.5 使用乘法分配率 设实系数一元二次方程x^2+ax+2b-2=0有两个相异实根,其中一根在区间(0,1)内,另一根在区间(1,2)内,则(b-4)/(a-1)的取值范围是我知道这题可用线性规划做.想问下,为什么不能用韦达定理,也就是 4/5 x4+2/5x2+1/5x16 简便计算 怎么简算.0.5x2.5x12.5x64 实系数一元二次方程x²+ax+2b=0有两个根,一个根在区间(0,1),另一个根在区间(1,2)内,求:(1),点(a,b对应的区域的面积?(2).b-2/a-1的取值范围.(3).(a-1²)+(b-2)²的值域 六年级4/5x4+2/5x2+5/1x16怎么算啊? 1.25X0.32X2.5 简算 把一元二次方程-5x2+x-3=0的二次项系数变为正数,且使方程的根不变,则变形后的方程为().这是选项:A.5x2-x-3=0 B.5x2-x+3=0 C.5x2+x-3=0 D.5x2+x+3=0 (4.4x7.5x4.8)除以91.5x2.5x2.4)简便运算 1.25x0.32x250 简算 已知sina是方程5x2+7x-6=0的根求[sin(3π/2-a)tan(2π-a)]/[cos(π/2-a)cos(π/2+a)]的值 一个底面半径10米的圆柱形蓄水池能蓄水1570立方米如果在挖2.5米可以蓄水多少立方米 3、5x2、1,简便运算 (4.8x7.5x8.1)除以(2.5x2.7x2.4) 挖一个圆柱形蓄水池底面半径是5米,深是4米,这个蓄水池可蓄水多少立方米?(用综合式计算) 简便运算:11分之2x7分之5+11分之5x2又7分之6,对的我一定立马采纳, 2/5x2/10+9/10x0.4-2除以5x1/10,x:是乘,尽快,我明天要演讲了
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn