自文档化代码并非如此

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

我知道这篇文章会引起很大的争议，但我还是要写。

自文档化代码并不是一个好的目标。在我看来，恰恰相反。

代码注释的存在有很多原因。其中之一是说明代码的功能，而自文档化代码（SD代码）正是试图消除这种注释。这并非坏事，因为如果代码需要注释来解释其功能，那就说明它过于复杂了。

另一种注释形式是解释代码为何如此运行。这比解释代码运行了什么更重要，因为代码本身并不能直接说明原因。这可能涉及到代码设计决策、产品设计决策、大型架构决策，或者其他各种各样的原因。

另一种评论形式是指向外部资源的链接。这可以是问题跟踪编号、设计文档或许多其他内容。

最后，有时候你确实需要记录下某件事的整体运作方式，因为整个算法很复杂，不可能让每个人都阅读所有代码来获得整体概览。

因此，在努力使代码简洁、清晰、易于理解的同时，不要过度删除所有代码注释，因为它们还有其他用途。