删除评论

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

在我发表了关于“童子军精神”的文章后，我发现大部分讨论都集中在代码注释上。具体来说，童子军精神的这一部分就是删除注释。关于删除注释的技巧也是我最受欢迎的代码清理推文之一。

最近在代码审查中，删除注释的问题再次被提及：

// filter out contacts that have unsubscribed
$contacts = $unsubscribedFilter->filter($contacts);

// filter out duplicate contacts
$contacts = $duplicateFilter->filter($contacts);

审阅者问我，为什么我在精简代码后“删除了文档”：

$contacts = $unsubscribedFilter->filter($contacts);
$contacts = $duplicateFilter->filter($contacts);

我稍后会再谈到注释和文档之间的区别。目前来看，它们确实存在区别，我删除的确实是注释。

首先，我要向所有发出呼声的团队负责人和工程经理们致谢：

删除评论？！！

是的，我建议你删除代码中的注释。

你肯定不是指删除有用的评论吧？

那么，什么才算有用的评论呢？

让我们先来区分一下注释和文档。文档指的是格式化的注释块（例如 DocBlock、JavaDoc 等）。注释则涵盖其他所有内容。

注释应该阐明原因，而不是内容或方法。换句话说，如果某些信息无法通过阅读代码来理解，那么就需要添加注释。

回到代码审查，注释里并没有包含代码本身没有表达的内容。从赋值和方法名就能推断出我们正在“过滤重复联系人”。所以上面的代码注释毫无用处。事实上，我浪费了时间去读它。

对我来说，删除注释是为了编写更清晰易懂的代码。甚至可以重构代码以提高可读性。例如：

$contacts->filterUnsubscribed();

注释有时有用，有时却会误导人。我经常遇到一些过时的注释，它们并没有随着代码的更改而更新。最近，我需要修复以下这段遗留代码，它会导致程序过早终止。

foreach ($items as $item) {
    if ($item->published) {
        // we've hit the most recent item before this push, so stop looping
        exit;
    }
}

注释说要停止循环，但代码却直接退出了。我浪费了好几分钟纠结到底该相信哪个。考虑到这个 bug，我修改了代码，按照注释的指示停止了循环。但即便没有这条注释，这个 bug 也本来是可以解决的。注释加上代码本身的缺陷，反而弊大于利。

这才是关键所在——做好事。让一切变得比你发现时更好。这就是为什么它被称为“童子军精神”。如果你遇到可以删除的评论，就把它删掉。如果删不掉，那就看看能不能重构代码，以便删除这条评论。未来的开发者会感谢你的。即使那个未来的开发者就是你自己。

我最终找到了罗伯·派克关于评论的以下一段话，这段话非常有效地概括了整篇文章。

注释是一件需要技巧和判断力的事情。我倾向于删除注释，原因有几个。首先，如果代码清晰易懂，并且使用了良好的类型名和变量名，那么它本身就应该能够解释清楚。其次，编译器不会检查注释，因此无法保证注释的正确性，尤其是在代码修改之后。一条误导性的注释可能会造成很大的困惑。第三，还有排版方面的问题：注释会使代码显得杂乱无章。

想了解更多代码清理技巧？我正在撰写一本“实战指南”，其中包含许多真实案例，帮助你编写真正持久耐用的代码。立即注册，抢先体验！