不要为坏的代码写注释，重写它

Don’t comment bad code?—?rewrite it — Brian Kernighan 不要为坏的代码写注释——重写它

为粗制滥造的代码片段着重写注释是不够的，如果您遭遇到一段这样的注释，您应该发起一个问题（issue）从而记得后续重构它。技术债务只要不是过多就没有关系。

在标准库的惯例是，批注一个 TODO 风格的注释，说明是谁发现了坏代码。

// TODO(dfc) this is O(N^2), find a faster way to do this.

注释中的姓名并不意味着承诺去修复问题，但在解决问题时，他可能是最合适的人选。其他批注内容一般还有日期或者问题编号。

与其为一大段代码写注释，不如重构它

Good code is its own best documentation. As you’re about to add a comment, ask yourself, 'How can I improve the code so that this comment isn’t needed?' Improve the code and then document it to make it even clearer. — Steve McConnell 好的代码即为最好的文档。在您准备添加一行注释时，问自己，“我要如何改进这段代码从而使它不需要注释？”优化代码，然后注释它使之更清晰。

函数应该只做一件事。如果您发现一段代码因为与函数的其他部分不相关因而需要注释时，考虑将这段代码拆分为独立的函数。

除了更容易理解之外，较小的函数更容易单独测试，现在您将不相关的代码隔离拆分到不同的函数中，估计只有函数名才是唯一需要的文档注释了。

此文已由作者授权腾讯云+社区发布，更多原文请点击

搜索关注公众号「云加社区」，第一时间获取技术干货，关注后回复1024 送你一份技术课程大礼包！