原标题:什么时候应该避免注释代码?
本文由玩赚乐(www.banghui.org)– 小峰原创翻译,转载请看清文末的转载要求,欢迎加入技术翻译小组!
看到标题,我知道你可能会想:“我为什么要避免代码注释,这难道不是一件好事吗?”。是的,写注释在大多数情况下是有用的。但是,请注意,我说的是“在大多数情况下”,因为有一些情况下,你不应该写注释。
还不相信?那让我告诉你:写注释有时会坏事!会导致坏代码!
请允许我用一句名言来开始我的论证:
不要注释坏代码——重写吧。——Brian W. Kernighan and P. J. Plaugher
这句话给我流下了非常深刻的印象。仔细想一想,有多少次你注释你的代码,只是因为担心自己将来再回过头来阅读的时候可能会不理解它的意思?至少都做过一次吧。坦率地说,我有很多次是因为这个原因才注释的,尤其是在那些我还是重构和编写干净代码的新手的日子里。
那么,为什么这样的注释反而不好呢?简而言之是因为,我们会因为有注释而放任编写坏的代码!正如你所看到的,注释有时候反而激励了我们去写一些不整洁的代码。
另一个原因是因为注释会误导我们。有多少次你已经改变了代码,却忘了改旁边的注释?别否认,这种事时常发生。这就是为什么你经常听到这样一句话,“真理只存在于代码中”。
那么,什么时候你不应该写注释呢?
有一个经验法则就是,无论何时你发现自己要使用注释来解释这段代码是用来干什么的时候,那么基本上就是你的代码需要重构以变得更整洁的时候。
典型的解决方案
现在你知道为什么有时候反而要避免写注释了,那么有什么解决办法吗。事实上,目前还没有一个有效的解决方案,但是你可以清洁你的代码,这样你(以及其他人)就可以在没有注释的情况下也能理解它了。
为了用可读的代码替换掉注释,通常我们的典型解决方法是使用提取方法重构(Extract Method refactoring)。这种重构方式是我最喜欢的。对此我也写过一篇博客,里面有完整的例子:《Break Your Method Into Smaller Ones》。
下面让我们看一个简单说明如何提高你的代码,从而解放注释的例子。
<?php // Check to see if the customer can get free product if ($customer->isPremium() and $customer->numberOfPurchases > 8) { } // OR if ($customer->canGetFreeProduct()) { }
我希望你能注意到这两个条件语句之间的差异。哪一个更整洁?很明显第二个更整洁,更好。这是因为,首先,可以删除注释,因为我们看代码就明白了意思。其次,也是最重要的一点是,我们提取了检查客户是否值得获得免费产品的逻辑到它的方法中,这是一件好事,特别是当你想要在应用程序中再次使用它的话。
对于更详细的例子,我推荐你阅读我以前发表过的文章。
结论
请允许我用一个免责说明来结束这篇文章。我不反对注释。注释在大多数情况下是非常有用的,尤其是在开源项目中。
我想说的是,你不应该为你的坏代码注释。请记住,“真理只存在于代码中”。
译文链接:
英文原文:When Should You Avoid Commenting Your Code?
翻译作者:玩赚乐(www.banghui.org)– 小峰
[转载必须在正文中标注并保留原文链接、译文链接和译者等信息。]
相关:
继晒娃、晒美食、晒旅游照之后,朋友圈掀起了了一阵晒跑步步数的热风。为了追求步数记录
上周我们刚刚报道了荷兰设计事务所 MVRDV 在在荷兰阿姆斯特丹做的一处网球俱乐部,最近他们又有新项目落成
挪威奥斯陆北部的耶夫纳克尔自治区(Jevnaker)有一个漂亮的雕塑公园,Kiestefos 雕塑公园,展出挪威以至世
美国职业女装品牌 Carrie Hammer 来上海时装周走秀的那天,Yudi 也去看秀了。虽然还算个时尚人士,但这次时
整个 9月和10月,时装月里的时装秀一场接一场,T 台上也一片叮呤咣啷声。 这个几乎可以听到的声音来自珠宝
程序员薪水有高有低,有的人一个月可能拿30K、50K,有的人可能只有2K、3K。同样有五年工作经验的程序员,可
作为中国第一个空间实验室,天宫一号目标飞行器已经于2011年在酒泉卫星发射中心发射升空。天宫一号任务的成
举个例子。当你看到一只喵星人,觉得很萌很治愈——这就是一种意识。“意识”是指对外部世界的主观体验,也
作为一个产品新人,入职之后,首先就要开始撰写各种文档。而在我看来,其中最重要的非产品需求文档莫属。产
新闻说科学家发现有外星文明迹象,但科学家的研究其实是这样的……
可以从这个地方找到这文章。http://arxiv.org/abs/1509.03622。总体上说,文章中没有提到和外星人的一毛钱关