我认为，质疑某一行代码是否具有自文档性是有意义的，但最终，如果你不理解一段代码的结构和功能，那么大多数时候注释是没有用的。以amdfan的“正确注释”代码片段为例:

/* compute displacement with Newton's equation x = v0t + ½at^2 */
const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

这段代码很好，但下面的代码在大多数现代软件系统中同样具有丰富的信息，并且明确认识到使用牛顿计算是一种选择，如果其他一些物理范式更合适，可能会被改变:

const float accelerationDueToGravity = 9.81;
float timeInSeconds = 5;
float displacement = NewtonianPhysics.CalculateDisplacement(accelerationDueToGravity, timeInSeconds);

根据我个人的经验，很少有绝对需要注释的“正常”编码情况。举个例子，你有多频繁地使用自己的算法?基本上，其他一切都是构建系统的问题，以便编码器能够理解正在使用的结构以及驱动系统使用这些特定结构的选择。

自文档代码是一个很容易解决的问题，随着时间的推移，代码、注释和文档会出现分歧。编写清晰的代码也是一个约束因素(如果你对自己有那么严格的话)。

对我来说，以下是我努力遵循的规则:

Code should be as easy and clear to read as possible. Comments should give reasons for design decisions I took, like: why do I use this algorithm, or limitations the code has, like: does not work when ... (this should be handled in a contract/assertion in the code) (usually within the function/procedure). Documentation should list usage (calling converntions), side effects, possible return values. It can be extracted from code using tools like jDoc or xmlDoc. It therefore usually is outside the function/procedure, but close to the code it describes.

这意味着所有三种记录代码的方法都很接近，因此更有可能在代码更改时被更改，但它们所表达的内容并不重叠。

I think its a matter of the right amount of documentation, rather than all or none. If the parameters to a function are well named, you often don't have to say exactly what they are, e.g. char *CustomerName is pretty obvious. If you use assert value ranges for parameters, you don't have to document those ranges as well. IMO, documentation should cover everything which is less than obvious and hence needs some explanation, and most code needs some documentation. Personally, I'd rather see an illustrative example of how a given function works than descriptive documentation, in most cases.

为了文档而编写文档可能会浪费时间，因为文档需要维护，以便与代码库保持同步。如果没有人会从阅读中受益，那就不要写。

我很惊讶居然没有人提出“识字编程”，这是一种由德克萨斯州的Donald E. Knuth在1981年提出的技术，并因《计算机编程的艺术》而闻名。

前提很简单:既然代码必须被人类理解，注释被编译器简单地扔掉，为什么不给每个人他们需要的东西——对代码意图的完整文本描述，不受编程语言要求的限制，为人类读者和编译器提供纯代码。

识字编程工具通过为文档提供特殊标记来实现这一点，这些标记告诉工具哪些部分应该是源代码，哪些部分是文本。该程序随后从文档中提取源代码部分并汇编代码文件。

我在它的网页上找到了一个例子:http://moonflare.com/code/select/select.nw或HTML版本http://moonflare.com/code/select/select.html

如果你能在图书馆找到Knuth的书(Donald E. Knuth，文学程序设计，斯坦福，加利福尼亚:语言和信息研究中心，1992,CSLI课堂笔记，没有。27.)你应该读一读。

这是自文档化的代码，包括推理等。即使是一份很好的文件， 其他一切都是写得很好的评论:-)

我曾经和一个家伙一起工作，他打算把金融套件卖给一家大公司。他们坚持让他记录源代码，他写了一个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)

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

在顺序:

Self-documenting code is code that clearly expresses its intent to the reader. Not entirely. Comments are always helpful for commentary on why a particular strategy was chosen. However, comments which explain what a section of code is doing are indicative of code that is insufficiently self-documenting and could use some refactoring.. Comments lie and become out of date. Code always tells is more likely to tell the truth. I've never seen a case where the what of code couldn't be made sufficiently clear without comments; however, like I said earlier, it is sometimes necessary/helpful to include commentary on the why.

然而，需要注意的是，真正的自文档化代码需要大量的自我和团队纪律。您必须学会以声明的方式编程，并且必须非常谦虚，避免使用“聪明”的代码，而应该使用那些似乎任何人都可以编写的代码。