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

避免代码注释的五大理由

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

十大界面原型与布局工具 Google产品经理Kenneth Norton:如何与工程师共事 如何创建自适应系统来增强用户体验 Jolla下月展示首款Sailfish手机 将重点发展中国区 海外1GB大容量游戏,国内渠道如何分发? 真正的能源大户是WiFi网络 数据中心只是“伪军” CloudFlare创始人传奇人生:7岁编程,法学博士,获哈佛商学院最高荣誉 2013云计算深入实践 jQuery 2.0发布 不再支持IE 6/7/8 Google再发力,更新Dart M4! 【多图】鼠标、光驱等13个即将消失的PC技术 直击OpenStack美国峰会:分享五大经验收获 Project Savanna:让Hadoop运行在OpenStack之上 看Go桌面技术副总,如何解读Facebook Home 增长最快的游戏公司Supercell 你学得会? 移动周报:为什么我们出不了IT神童? AWS、VMware和OpenStack谁是赢家? 消息称苹果正在寻找新任CEO取代库克 请别人云亦云 PC仍然重要且活得很好 比预想晚几年!IBM x86服务器或终将卖给联想 App推广的节操呢? iMessage垃圾短信产业链暗访 Apkudo CEO访谈:免费为Android开发者提供测试 Web API核查表:设计、测试、发布API时需思考的43件事 开源Android构建工具Buck 速度超Ant两倍 从史上八大MySQL事故中学到的经验 OpenStack Heat向应用市场更近一步 初创公司Ionic Security:云安全必须与时俱进 谷歌董事长:一年后消费者才能用上Goolge Glass Windows 8.1重新推出的“开始按钮”毫无意义 手眼并用 代码泄露三种Google Glass手势操作 Google新论文 CPI²:基于Linux的世界级跨数据中心服务器CPU监控 为什么接到集线器上的网线会一闪一闪的! insert into的问题,看是简单,但却不简单。。。 vb绘图问题 请问加入什么代码才能在下面的程序中实现分页!??谢谢! 如何判断局域网内另一台机器上的一个NT服务是否启动? 一各递归的问题。 寻求有关NAND FLASH 和支持他的文件系统的中文资料 Access数据库应该用什么数据库引擎驱动? 各位,谁有InstallShield Express 3.53 15天使用版的激活码阿 ado 中的数据库动态查询 好久没上来了,请大家谈一谈portal吧..... 连接 Access数据库应该用什么数据库引擎驱动? 怎么做到你在Copy文件,遍历目录时.进度条和操作过程一至呢? 如何在XP下设置打印机的纸张 请问如何获取DataList的EditItemTemplate中的自定义控的属性? asp.net(C#)里,如何判断一个数据库的字段是否为null? 世界杯和队歌集锦 在汇编中,如何实现延时 Outlook的问题,很急!!!在线等!!! 小弟最近需要注册一国际域名,可否提供一个地方? 诚征MCSD考友,本人上地上班 请大家指教 请教各位一个关于ADO的问题,很奇怪 应用程序性能评测器 (APE,Application Performance Explorer)大家有没有使用经验?来交流以下了! 关于outlook express和MSN Messager的问题 我想从指定的文件初始化 Bitmap 类的新实例。我怎样才能更改那个新实例的大小和分辨率呢? 各位软件开发人员:大家都看到了IT市场的不景气,你们各自有什么看法,请发表意见!!! 送分了! 菜鸟提问: 用TDBNavigator + DBGrid删除记录时,会弹出一个英文的删除确认对话框,请问如何去掉该对话框? 急!!!win2000 server安装server pack 2重新启动进入系统后,一切都变成黑白的了???怎样解决?谢谢! 大家帮忙,哪里有datalist中绑定datalist或者datagrid的例子啊? 分啊 程序发布 dephi中用哪个函数可以解决两个日期的差,要求精确到分钟! 谁知道ipvod的透屏技术? 怎么从没有信任关系的网域的机器B上copy文件?有一个可以访问B的账号和密码. jsp中如何实现树状结构? applet 与servlet的通讯 请大虾们进来看看 请问大家如果使用了两个session会有什么影响吗?? 中国古典四大名著教给我们什么? 在iis中,如果需要让访问每个主页的用户都看到一个主页通知,该怎么做?就好象是做一条广告一样 怎么开始学习JAVA,没有c++的基础,很困惑 请教专家高手有什么好建议,谢谢 wingsun,bcb等大虾帮小弟看看这个"参数错误"的问题.谢谢 如何理解连接身份 如何用TURBO C编背景音乐? 我用exec() 来执行notepad.exe , 用它来打开我想要的文本 , 可是并没有得到notepad.exe执行。 你是想找一个爱你的人还是会找一个你爱的人? VC++中如何列出SQL_SERVER服务器?急救!!! manner的意思? 怎么做高一物理的追及问题和相遇问题? 油膜法计算已知油酸酒精溶液的浓度为1‰,一滴油酸溶液在水中扩展的油膜面积约为186cm2,1mL油酸溶液约有66滴,则测得的油酸分子的大小为_________________. manner什么意思 两辆完全相同的汽车沿水平道路一前一后匀速行驶,速度均为Vo,若前车突然以恒定的加速度a刹车,它刚停住时,后车以加速度2a开始刹车,已知前车在刹车过程中所行驶的路程为x,若要保证两辆车 擦玻璃器的吸铁石粘在一起如何分开 in a .manner是什么意思 某高速公路在大雾天气下能见度50m,司机的反应时间为0.5s,汽车在车况良好时刹车可达到的最大加速度为5m\s2,为确保安全,车速最高不能超过( )A.72km\h B.36km\h C.54km\h D.46km\h 粘在身上的磁铁如何分开? 传统文化历史文化好词好句 德干高原来源于? 想看看关于人间真情的影片.最好是能感动人的,和启迪我们以人生哲理.要有影片的名字.我喜欢《阿甘正传》《山楂树》《忠犬八公的故事》《我在雨中等你》等这类的电影.请大侠们帮帮忙. 一块磁铁从中间截断,为什么不能吸到一起?按照道理,断了之后中间的两极应该是异性,应该吸到一起,可是实际情况是弹开.可能你小时候也试过,摔断了就不能吸到一起了,而是相坼的 ☆不要在 德干高原在地图的哪边? 关于碳酸氢钠和碳酸钠.甚么时候生成那种?0.2mol丁烷完全燃烧后生成的气体全部缓慢通入0.5L2mol/LNaOH溶液中,生成的Na2CO3和NaOH溶液中,生成的Na2CO3和NaHCO3的物质的量之比为? 用电磁铁将金属制品分离出来 这种做法为什么是不合理的阿大神们帮帮忙垃圾分类回收对资源的充分利用及环境保护有重要意义.下列对垃圾的处理方法中不合理的是( ) A.将回收的废旧 拔火罐的火是什么火 求八下历史期中试题(人教版)至少10道题以上,有一道材料题,急 220v电机引出线只有三条,怎么接正反转?(图) 拔罐的作用?我颈椎不舒服 23岁 适合拔罐吗?对于身体健康的人拔罐有好处吗? 人教版语文的期中试题谁有啊速度越快越好,没多少时间了 CaO+H2O=2Ca(OH)2现象是什么 拔罐有什么好处?会有后遗症吗?30岁能不能拔罐?患者信息:女 25-34岁 汽车正以10米每秒的速度在平直公路前进,突然发现正前方有一辆自行车正以4米每秒的速度做方向相同的匀速直线运动,汽车立即关闭油门做加速度大小为0.6的匀减速.(我不要答案我只想问)“ 利用直流高压电源如何使物体带静电,或如何产生静电场.我手头上现有6KV直流高压电源.怎么接?急 拔火罐的火怎么弄 哪有静电喷塑的工艺流程? 请问有以直流为电源的高压(50—80KV)静电发生器吗?如果把两块(约20x20cm)大小的相对对地绝缘的金属板平行放置,金属板间距约5cm的话,大约需要施加多大的同极静电电压才能在它们之间产 同步发电机定子和转子的作用.? 1935年前苏联的一条直铁轨上,有一列火车因蒸汽不足而停驶,驾驶员把货车厢甲留在现场,只拖着几节车厢向前不远的车站开进,但他忘了将货车车厢刹好,使货车厢在斜坡上以4m/s的速度匀速后退 家电展厅接了地线怎么会所有金属物体都带静电?展厅把电源全部关闭,金属物体还是带静电而且只要在展厅里面桌椅金属边框也会有静电.今天去查地线,将钳子放在玻璃桌上,过了一会,钳子也 发电机定子与转子由什么构成?我说的电厂直流同步电机 静电喷塑可以先喷一层颜色再喷一层透明的吗?如果可以.请问如何操作.我这一个是要喷在衣架上面的请介绍哪里有卖材料?要便宜的 传统文化好词好句 为什么矿泉水和纯净水都有保质期? 推荐几部有深刻含义的电影好写观后感的 直流电动机电枢电动势的作用是什么呀? 纯净水和山泉水(矿泉水)哪个保质期长?为什么? 求几部好看的电影!看后有启发,有意义的!如题 请不要复制.不要太老的. 请问高手 "MACBETH Color Booth" 这个专有名词该怎麼翻译? 我们平常喝的塑料瓶装矿泉水、纯净水为什么保质期是一年?普通的水放两三天就不能喝了,为什么瓶装水会保质那么长时间?是不是放了防腐剂?对人体有没有害? 生成氧气的3个化学方程式? 哪个海峡把东南亚分成了中南半岛和马来群岛两部分 水有没有保质期.如何保存瓶装矿泉水和纯净水我偶尔发现1箱2年前的矿泉水.保质期写的是1年.还能不能喝啊.看起来没有什么异常 一公斤静电喷塑的塑粉(浅驼灰,RAL7032)能喷多少个平方?假定是0.08mm的厚度 如何把 俩个吸力很大的磁铁 分开 利用双氧水制造氧气的化学方程式 急!请问静电喷塑粉一公斤能喷几个平方如果喷在钢板制品上,一个平方总的成本在多少(包括前处理,磨腻子等等)?要是建一个喷塑需要购买哪些设备,价格大概是多少?请各位帮帮忙,比较急. 下列地区属于热带季风的是 ①马来群岛②西亚③南亚④中南半岛 A ①② B ②④ C ①④ D②③ 化学方程式氧气 有没有人知道静电喷塑中的塑粉化学成份是什么? 东南亚主要包括中南半岛和马来群岛两部分 对么?今天必须告诉答案才给悬赏分我记得应该是 东南亚是由中南半岛、马来群岛和很多岛屿组成的 明天就考期中了 在今天回答啊! 氧气所有化学方程式 静电喷塑设备喷什么产品 把火柴平放在蜡烛燃烧的火焰中,1秒后取出火柴,哪里烧得最黑? 从黑龙江虎林到天津的运输(火车)费是多少?运大米,每吨多少钱,或者一车皮多少钱 求八下语文答案 booth manner怎么翻译~~什么意思 谁有电影看了可以有人生哲学类的启发推荐不用太多,多了也看不完啊. 转盘之间需要有润滑油进行润滑,油膜的厚度必须达到一定的值才能保证润滑效果,如何确定这个油膜厚度?
备案号:鲁ICP备13029499号-2 说三道四 www.s3d4.cn 说三道四技术文摘