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

避免代码注释的五大理由

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

分割图像的原理 -VB资料 封面的设计 -VB资料 改变 Win95 的 Shell -VB资料 改变墙纸 -VB资料 格式化磁盘 -VB资料 跟我学用ActiveBar-VB资料 VB获得IE的版本号 VB获得Windows启动方式 VB获得打印机驱动程序的设定 VB获得当前计算机上的区域设置 VB获得当前用户名 VB获得分区信息并判断是否有CD VB获得某个文件夹下的所有子目录 VB获得驱动器的卷标 VB获得系统中的所有字体列表 VB获得系统中鼠标的键数 获取驱动器信息-VB资料 文章主题: 获取桌面图象 -VB资料 计算两个日期间的工作日-VB资料 监视外部程序的运行情况-VB资料 检测文件是否存在 -VB资料 检测系统驱动器-VB资料 检查电子邮件地址输入的有效性 -VB资料 检查硬盘空间 -VB资料 将数据转换为内存二进制形式字符串(模拟CV?和MK?$两组函数) -VB资料 禁用 Alt-Tab 或 Ctrl-Alt-Del -VB资料 禁止使用 Alt+F4 关闭窗口-VB资料 绝非玩笑:VB7将完全面向对象 拷贝磁盘 -VB资料 控制Ctrl+Del+Alt键-VB资料 快速编辑VB程序技巧 怀念朱总理!! 关于内存泄漏的问题!! 要用XSL原样输出一个元素里面包含的所有内容怎么办? IHTMLDocument 怎样得到一个tag的属性值 简单问题 没有激情以后还能干什么? 如何实现基于对话框的程序不在任务条里显示? 十六大闭幕 用Delphi、Mysql的大侠帮忙看看吗?---急急急急 别人的东西,学习c的朋友看看吧。 高手请指点! 表示严重不满:jbuilder下居然不能用鼠标的滚轮~ 如何将HTML文本直接显示在CppWebBrowser中?(不使用临时表) PB中有没有类似VC中ListMember功能的东东呢? 怪啊怪啊,ListView的问题 如何取得任务栏的高度? 哪里有《Effective STL》下载? 哪里有《Effective STL》下载? Load Servlet ? word 和 数据库 谁能帮我看一下程序? 帮我看看这几个宏什么意思? 程序员!女人对你重要么???? 这是我第四天的C#学习笔记,敬请高手指教 谁先回来马上给分(简单问题) 机器的usb问题!! 兄弟们,小弟刚接触JSP,帮忙解决一个问题。 请教PHP.INI配置里的SESSION! 刚开始接触.net 求购程序,请进. 求购程序 求购程序 推荐一些适合初学者看的书吧 一家位于Montreal, Canada的公司,求购一个程序 如何保存UNICODE的字符串到硬盘上 如何将HTML文本直接显示在CppWebBrowser中?(不使用临时表) 如何保存UNICODE的字符串到硬盘上 redhat第4第5两个iso文件是做什么的 关于jsp做客户端调用ejb的问题?????望各位兄弟们救救我吧!!!!! COOL!将所有菜单设置为半透明的代码(只适用于WIN2000以下版本) 请问谁知道如何用jakarta-jmeter进行压力测试? 如何判断文件夹是否存在 在Win2K Server安装Oracle817时,没有安装数据库,后在创建数据库时出现"ORA-12560:TNS:协议适配器错误"... 请教.net服务器问题 解决这个问题,给你200分!!!!!!!!!!(回头追加给你!) 我是初学者,请问.net framework先进性在哪里? 有谁试过用JAVA编FTP软件? 很简单的listBox问题,HELP 今年大四,现在找工作,求助,我怎么样………UP有分。 寻找!! IE的文本输入框,输入一字符会联想,请问怎样去掉这个联想?(Win2K) 右边那个字怎么读? 两个减函数相乘仍然是减函数吗?定义域为R上单减,如题 谢谢!是相乘 不是相减... 查字的读音(三点水加上面是个口,下面是个巴)的这个字 越字右边读什么 怎样用“就像”.“又像”造句?(两个词语都要用上) 三点水+1个“我”是个什么字?但是确实是有这个字的. left sth at home中at可以省略吗?rt 像里应外和相似的词语有哪些 请帮我找一下“轻轻地”类似这样的词 left my sth at home中文翻译 像悄悄爬类似的词语 went back home中home什么词性 1.细小:微小.( )2.形容路途遥远.( )3.看(书报)并领会其内容.( ) 选择 What's this - ( )"A" A.It's B.It's an C.It's a D.This is 有一个词,意思是吃,其中一个字是服,这个词是什么. 佛是真实存在,还是精神上的存在?必须善心善行才能获得大利益,还是发慈悲心就能得大利益呢?所谓自度度人,我所说的大利益是成就自己,而非世俗的名闻利养.如果说信则有,不信就无,那你一 英语翻译RT 指南这个词是什么意思? 佛是真实存在过的,还是人们心中的信仰究竟是那个时期真实存在的,还是人们对美好生活的向往,是心中的信念呢 麻烦各位帮我翻译一下这句话,翻译成英语.不知道是自己太没用了,还是爱得太过火,明明决定好的事情,居然那么容易变挂,如果哪天结果并不是我想的那样,我想我会疯掉.伴着担心与害怕,我决 阅历什么意思、两次用“自以为”这个词表现了什么、 单位脉冲函数的数学定义是什么?有什么实际的物理意义?单位脉冲函数与普通函数相乘 matlab的平方指令 比如说n个a(数字)相乘 怎么用函数写 采用后另有高分 广东话淡这个字怎么发音啊? 请问多个不同函数相乘如何求一阶导?如ABC的导数若其中都是复合函数呢? 如何在matlab中使得输出的传递函数是因式相乘的形式 建立希望工程就是为了能够实现贫穷孩子们的梦想翻译成英语 英语翻译I will make myself anew,relentlessly,devotedly,for this summer,for this,now!这个句子从翻译上,用词上,语法上有问题吗,可以这样用吗?那个for this 的意思是?想表达这个意思:在这个夏天,现在,我将会 下列行星中,卫星最多的是 A、木星 B、土星 C、火星 D、海王星 书是钥匙,能开启智慧之门.书是?仿写!多点, 连词成句color,is,what,eraser,this(?) 以下行星中,卫星数最少的是 木星,土星,火星,水星 写出含有“手”字的成语形容聪明( ) 形容冷淡( )形容亲密( ) 形容高明( )形容凶狠( ) 形容没准备( )千 钧 一 发千 军 一 马千 ( ) 一 ( ) 她是我的榜样(英文)! 宇宙的行星有比木星的大吗木星在宇宙是第一大把~不是把 先在知道的行星有比木星大的有吗 英语翻译一日院主请师上堂.大众才集.师良久.便归方丈闭门.院主逐后曰.和尚许某甲上堂.为什麼却归方丈.师曰.院主.经有经师.论有论师.律有律师.又争怪得老僧.师问云岩.作什麼.岩曰.担屎. 榜样英语是什么 买消毒柜,樱花消毒柜和华帝消毒柜选哪种好? 用英语翻译"这个真理放之而皆准" 两个函数乘积有什么几何意义? 1.Lucy had already completed the project when I arrived.(改一般疑问) 时间见真理用英语怎么翻译 itis D的问句为什么是what is it而不是what is this 哪种消毒柜好?请问下面两种消毒柜哪种好一点,请说出理由,越详细越好,谢绝大篇理论灌水:康宝消毒柜 嵌入式消毒柜ZTP108E-11T(1)万家乐 嵌入式消毒柜YTD100-W2(W2A) 翻译并解释用法La poste est par la.重点是par la 我们说哲学的智慧产生于人类的实践活动我们又说哲学源于人们对实践的追问和对世界的思考二者是否矛盾为什一方面我们说哲学的智慧产生于人类的实践活动,另一方面我们又说哲学源于人 类似的词语 the thieves had already gone.变成反义疑问句 儿童有哲学思维吗?结合你的实践,试举出两例.如题 用英语来形容这些人物的样子 I am Lucy.怎样改为一般疑问句? 王字傍右边寻字怎么读 如何用英文形容圆明园的样子?最好是一小段话, 与大大小小同类的词语 you took an optional course this semester.请翻译一下, 两个定义域为全体实数的奇函数相乘,得到的一定是偶函数吗? 穿的英文 how do you like this course 如何翻译?如何回答 已知一个函数的定义域,怎么求两个函数的和的定义域若ƒ(x)的定义域为[0.1],求ƒ(x+a)+ƒ(x-a)的定义域 补充句子.书是钥匙,能开启智慧之门;书是.
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘