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

Posted 2020-07-18 o0孤独夜莺0o

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

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

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

不要注释坏代码——重写吧。——Brian W. Kernighan and P. J. Plaugher

　　这句话给我流下了非常深刻的印象。仔细想一想，有多少次你注释你的代码，只是因为担心自己将来再回过头来阅读的时候可能会不理解它的意思？至少都做过一次吧。坦率地说，我有很多次是因为这个原因才注释的，尤其是在那些我还是重构和编写干净代码的新手的日子里。

　　那么，为什么这样的注释反而不好呢？简而言之是因为，我们会因为有注释而放任编写坏的代码！正如你所看到的，注释有时候反而激励了我们去写一些不整洁的代码。

　　另一个原因是因为注释会误导我们。有多少次你已经改变了代码，却忘了改旁边的注释？别否认，这种事时常发生。这就是为什么你经常听到这样一句话，“真理只存在于代码中”。

　　那么，什么时候你不应该写注释呢？

　　有一个经验法则就是，无论何时你发现自己要使用注释来解释这段代码是用来干什么的时候，那么基本上就是你的代码需要重构以变得更整洁的时候。

　　典型的解决方案

　　现在你知道为什么有时候反而要避免写注释了，那么有什么解决办法吗。事实上，目前还没有一个有效的解决方案，但是你可以清洁你的代码，这样你（以及其他人）就可以在没有注释的情况下也能理解它了。

　　为了用可读的代码替换掉注释，通常我们的典型解决方法是使用提取方法重构（Extract Method refactoring）。这种重构方式是我最喜欢的。对此我也写过一篇博客，里面有完整的例子：《Break Your Method Into Smaller Ones》。

　　下面让我们看一个简单说明如何提高你的代码，从而解放注释的例子。

1 <?php
2 // Check to see if the customer can get free product
3 if ($customer->isPremium () and $customer->numberOfPurchases > 8) {
4 }
5 // OR
6 if ($customer->canGetFreeProduct ()) {
7 }

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

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

　　结论

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

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