自文档代码通常使用与代码所做的事情完全匹配的变量名，这样就很容易理解发生了什么

然而，这样的“自文档代码”永远不会取代注释。有时代码太复杂，自文档化代码是不够的，特别是在可维护性方面。

I once had a professor who was a firm believer in this theory In fact the best thing I ever remember him saying is "Comments are for sissies" It took all of us by surprise at first but it makes sense. However, the situation is that even though you may be able to understand what is going on in the code but someone who is less experienced that you may come behind you and not understand what is going on. This is when comments become important. I know many times that we do not believe they are important but there are very few cases where comments are unnecessary.

自文档代码是非常清晰的代码，以至于不需要注释。我举个小例子:

//iterate from 0 to 100
for(int i=0; i < 100; i++) {
   println i
}

注释没什么用，因为代码很清楚。文档是一个很好的实践，但是额外的文档会给代码增加不必要的干扰。你的同事需要知道的是，不是每个人都能阅读别人的代码并了解所有的细节。

int calc(int a, int b) {
   return sqrt(a*a + b*b); //pythagoras theorem
}

如果没有注释，最后一个片段将很难破译。你可以想象其他更做作的例子。

自我记录代码是“DRY”(不要重复自己)的一个很好的例子。不要在注释中重复代码本身中的信息。

与其解释变量的用途，不如重命名变量。

与其解释一个简短的代码片段做什么，不如将其提取到一个方法中并给它一个描述性的名称(可能是注释文本的缩短版本)。

与其解释一个复杂的测试做什么，不如把它也提取到一个方法中，并给它起个好名字。

Etc.

在此之后，您将得到不需要太多解释的代码，它可以自行解释，因此您应该删除代码中只是重复信息的注释。

这并不意味着你完全没有注释，有一些信息你不能放入代码中，比如关于意图的信息(“为什么”)。在理想的情况下，代码和注释相互补充，每个注释都增加了独特的解释价值，而不会重复另一个注释中的信息。

我相信您应该始终努力实现自文档化代码，因为它确实使代码阅读变得更容易。然而，你也必须务实。

例如，我通常为每个类成员添加注释(为此我使用文档注释)。这描述了成员应该做什么，而不是如何做。我发现，当我阅读代码，特别是旧代码时，这有助于我快速记住成员是用来做什么的，我也发现这比阅读代码和解决它更容易，特别是当代码流跳跃相当多的时候。

这只是我的个人观点。我知道很多人在工作时根本没有评论，他们认为这没有问题。然而，我曾经问过某人关于他们六个月前写的一个方法，他们不得不思考几分钟来告诉我它到底是做什么的。如果方法是注释的，这不是问题。

最后，您必须记住，注释和代码一样都是系统的一部分。在重构和更改功能时，还必须更新注释。这是反对使用注释的一个论点，因为如果它们不正确，它们比无用更糟糕。

我曾经和一个家伙一起工作，他打算把金融套件卖给一家大公司。他们坚持让他记录源代码，他写了一个30多页的汇编程序，并说“这是有记录的，看”——然后他翻到第13页，有一条评论“bump counter by one”。 伟大的产品，伟大的实现者，但是……

无论如何，在我看来，上面的重要评论是为了设置上下文。这段代码是自记录的:

> from BeautifulSoup import
> BeautifulSoup, Tag def
> replace_a_href_with_span(soup):
>     links = soup.findAll("a")
>     for link in links:
>         tag = Tag(soup, "span", [("class", "looksLikeLink")])
>         tag.contents = link.contents
>         link.replaceWith(tag)

但是，就我个人而言，需要一个背景来充分理解它。

好的设计结构有助于指出，有些函数是通用的，有些是随机的业务逻辑，即使你没有评论说“这个函数是通用的”。

We should not forget about design and specification documentation though. Those have or at least should have much of the texts that are not necessarily needed in comments. Software often have also user manuals and other description documents, and those should be in sync with what the program does. The situation is not great if the user has to find out what the software does from the source code instead of a manual. So self documenting code still doesn't mean that the actual software has been documented.

还要考虑功能的可跟踪性。当你有了你的手册，那么你应该能够追踪到源代码的特性，并返回更好的可维护性。手册和规范与编程没有太大关系，但它们与软件工程有关。软件越大，需要的工程设计就越多。