什么时候应该避免写代码注释？

看到标题，我知道你可能会想：“我为什么要避免代码注释，这难道不是一件好事吗？”。是的，写注释在大多数情况下是有用的。但是，请注意，我说的是“在大多数情况下”，因为有一些情况下，你不应该写注释。

　　还不相信？那让我告诉你：写注释有时会坏事！会导致坏代码！

　　请允许我用一句名言来开始我的论证：

不要注释坏代码——重写吧。——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 productif ($customer->isPremium () and $customer->numberOfPurchases > 8) {
}// ORif ($customer->canGetFreeProduct ()) {
}

　　我希望你能注意到这两个条件语句之间的差异。哪一个更整洁？很明显第二个更整洁，更好。这是因为，首先，可以删除注释，因为我们看代码就明白了意思。其次，也是最重要的一点是，我们提取了检查客户是否值得获得免费产品的逻辑到它的方法中，这是一件好事，特别是当你想要在应用程序中再次使用它的话。

　　对于更详细的例子，我推荐你阅读我以前发表过的文章。

　　结论

　　请允许我用一个免责说明来结束这篇文章。我不反对注释。注释在大多数情况下是非常有用的，尤其是在开源项目中。

　　我想说的是，你不应该为你的坏代码注释。请记住，“真理只存在于代码中”。

什么时候应该避免写代码注释？相关推荐

Redis是如何写代码注释的？
许多人认为,如果代码写得足够扎实,注释就没什么用了.在他们看来,当一切都设计妥当时,代码本身会记录其作用,因此代码注释是多余的.我对此持不同意见,主要出于两个原因: 1. 许多注释并未起到解释代码的作 ...
php代码注释处理类库,php代码注释
代码注释在多人开发的时候非常重要,现象一下,一段代码没有任何主要你去结合运行的效果去看实现的逻辑,那是非常费劲的事. 如果让别人看懂你写的代码,代码注释启动非常重要的作用.一个不会写代码注释的不是一个 ...
Linux不用来写代码,我使用过的Linux命令之:（冒号） - 啥也不做（除了……）
用途说明我们知道,在Linux系统中,冒号(:)常用来做路径的分隔符(PATH),数据字段的分隔符(/etc/passwd)等.其实,冒号(:)在Bash中也是一个内建命令,它啥也不做,是个空命令. ...
IntelliJ IDEA中的神仙插件写代码必备！
IDEA 全称 IntelliJ IDEA,是java编程语言开发的集成环境.IntelliJ在业界被公认为最好的java开发工具,尤其在智能代码助手.代码自动提示.重构.JavaEE支持.各类版本工 ...
聊聊写代码的20个反面教材
前言今天跟大家聊一个有趣的话题:如何写出让人抓狂的代码? 大家看到这个标题,第一印象觉得这篇文章可能是一篇水文.但我很负责的告诉你,它是一篇有很多干货的技术文. 曾几何时,你在阅读别人代码的时候,有 ...
IntelliJ IDEA中的神仙插件写代码必备
点击"终码一生",关注,置顶公众号每日技术干货,第一时间送达! IDEA 全称 IntelliJ IDEA,是java编程语言开发的集成环境.IntelliJ在业界被公认为最好的 ...
IntelliJ IDEA中好用的插件写代码必备
俗话说:＂工欲善其事必先利其器＂,今天准备和大家一起分享一下实际工作中能提升幸福感和工作效率的IDEA插件. 1.Alibaba Java Coding Guidelines [阿里巴巴代码规范检查插 ...
IntelliJ IDEA中的神仙插件写代码必备，别说你还不知道
IDEA 全称 IntelliJ IDEA,是java编程语言开发的集成环境.IntelliJ在业界被公认为最好的java开发工具,尤其在智能代码助手.代码自动提示.重构.JavaEE支持.各类版本工 ...
IDEA 神级插件！效率提升 30 倍，写代码必备
IDEA 全称 IntelliJ IDEA,是java编程语言开发的集成环境.IntelliJ在业界被公认为最好的java开发工具,尤其在智能代码助手.代码自动提示.重构.JavaEE支持.各类版本工 ...

什么时候应该避免写代码注释？

什么时候应该避免写代码注释？相关推荐

最新文章

热门文章