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

避免代码注释的五大理由

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

做动态显示的控件-Delphi资料 做一个OpenGL控件-Delphi资料 Api函数列表——与打印相关-Delphi资料 Delphi 5快速创建控制面板程序 Delphi 编写Windows NT服务 Delphi 的 分 发 工 具 ─ ─InstallShield Delphi 关于系统编程中的技巧 Delphi3如何调用Excel Delphi5.0中的函数调用模式 用Delphi 编 程 时 如 何 利 用 线 程 Delphi的8个技巧 delphi函数参考手册 DELPHI键盘常用快捷键汇总(DEFAULT 和CLASSIC) Delphi实现自动切换输入法 Delphi使用汇编 Delphi系 统 提 示 信 息 的 汉 化 DELPHI下的多线程程序设计 Delphi下汉字输入法的编程及使用 在Delphi与C++之间实现函数与对象共享 DELPHI中处理时间 Delphi中的INI文件编程 DELPHI中的消息处理机制 Delphi中对目录拷贝、删除和搬移的操作 Delphi中任务栏状态区的编程 Delphi中如何处理2000年问题 Delphi中如何实现系统权限的设置 Delphi中异常的截获及其个性化处理 Delphi自定义消息应用一例 Delphi5中资源文件的创建和使用 Delphi的Bug-Tthread Suspend方法 Email服务器的简单实现-Delphi资料 工作室征名,有礼物送啊! 请问怎样用foxpro自身的数据库做c/s系统,odbc,远程视图怎样用?给个小例子,谢谢! XP下的MEDIAPLAYER可以播放DVD吗?? 高手请进 谢谢回答 我学习了C,想考高程,如何开始啊? 三级都考什么呀?那里有全面一点的介绍? 各位高手,小弟请教一个问题 关于ADOConnection和ADODataSetCommand的问题,请大家帮忙 请问如何在一个JavaScript函数中调用另一段asp程序? 为什么我的XP需要我手动关机啊?? 请问TC3中如何产生一个1至9的随机数? 关于安装 KV 2003 失恋后的第一个中秋!散分! 才学C++的朋友,留个QQ,以便交流. 背投彩电买什么牌子/型号的好?大家出点意见 :) 中秋夜还有谁在技术版,问一个关于javascript的问题! Project 2002 快速下载 中秋,女友陪别人去了,我就来这里和大家共度佳节吧…… 现在上网真的很无耐,无耐。。。 HttpContext.Current?? 我们中秋,他们911! 一个表中,怎么写SQL使得不够5位的记录在后面自动加零补够5位! 以Post提交表单时的一个小问题 Socket可以实现这样的功能吗? 如何取消Linux 中的单用户模式 ? 怎样固定生成窗口的大小? 为什么在panel中不能响应image的onclick事件? 在CSDN过中秋节的兄弟们,来坐坐吧! 怎样关闭cformview派生的视图? 各位大虾,有谁知道怎么配置连接池呀,我以前配的,现在有点记不起来了,最好能说清楚点,谢谢!重分酬谢! 如何使位图在文档类视图中显示出来! 怎样快速获得一幅图像所用的颜色的总数? 错误号问题 如何在ie中直接打开word文件进行浏览、编辑,并保存。 一直都在接分,我也散点分。祝大家中秋快乐!!!!!! 我学应用物理,计算机该怎么自学?100+100=200 大分相送!不够再加(第1部) 有一个问题,怎么配置struts,有没有一个现成的例子呀,望指点,谢谢,也可以发到我的信箱 有CSDN上的兄弟一起过中秋节晚上,今晚不孤独,最后七十分散掉 oracle9i...数据库是提示:ORA-12154: TNS: 无法处理服务名 ? **首先祝大家中秋快乐,然后请问“包程序写入失败”是什么意思???**谢谢:-) 我学应用物理,计算机该怎么自学?100+100=200 大分相送!不够再加(第2部) 如何將數組定義在一段連續的內存空間??急急!!!!! **首先祝大家中秋快乐,然后请问“包程序写入失败”是什么意思???**谢谢:-) 我用这个函数Space$(nSize),提示说工程库没有,需要什么工程库? 两罐啤酒,独过中秋。祝这里的兄弟姐妹中秋快乐! 一个有关datareport的问题 现在有必要学ASP吗? 请教:为什么我不能给被调用包的源代码设置断点,请问是什么原因?怎么解决? 补刚才漏掉的五十分 想编写一个新邮件到达时自动通知的程序,请提供思路 关于SAX对大数据量文件的读写(高分) 受让球半是什么意思 受让半一球是什么意思 科学名词猜迷求几个科学名词,然后用几个词描述它的,比如影子—好朋友,形影不离,光的作用.描述词4到5个,不能太简单,越多越好!不要脑筋急转弯的 猜迷:二边夹击(打一三个字的数学名词) lg3次方根号下2+lg3次方根号下5 任何一个凸边形的内角中,为什么不能有3个以上的锐角 将来人们的生活水平农民过的是什么样的生活水平,城市与农村的区别 翻译:将来人们就不用钱了 未来几年岩土工程的就业前景 内容要有价值,最好有几何题.要有难度.题目至少10道,越多追分越高! 商务签证,旅游签证等等的英语是什么?就是B1\B2那些.所有的签证类型英文表示!商务签证,旅游签证等等的英语是什么?就是B1\B2那些.所有的签证类型英文表示.还有一般被加拿大拒签是什么原因? 白俄总统错坐普京座位 发现后起身让座伊朗边境发生武装冲突 14名边防人员朝鲜纪念中国志愿军赴朝参战63周年 世界浙商大会开幕 夏宝龙赞浙商是最倚人感染H7N9禽流感病毒疫苗株在杭州马尼拉巿长据报拟下月赴香港就人质事件俞正声谈中共十八届三中全会毒性很强的废水直接排放 瓯海一老板被从X光片CT片中提炼白银 丽水男子因杭州西湖特聘十大“刺客” 常年为西湖立塔打井 杭州首个井筒式停车库有望下的哥拾金不昧捡包送还乘客谁走人“今日头条”网正被立案调查将为行人设隔离桩式开口“王子抱”山西副省长杜善学、政协副主席令政策被段店、清河燃气客服站启用泺文路周日起全封闭俩月北京广州限价政策执行现松动齐风鲁运全球汉语时代,国人争考“对外汉语教师贼猫神眼战偶四分之三绝世美男网游之间谍人生光荣之路末世狩猎者南宋浮生记暴力召唤师绝世凶器异世之炼器专家统万城遗址旅游香炉寺旅游卧龙海旅游中庙旅游半汤温泉旅游丰宁坝上旅游天门寺旅游荔江湾旅游桂林訾洲公园旅游桂林市区水上游旅游孟屯河谷旅游
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘