以下是我对你的问题的最佳回答。

自文档代码是用类、方法、函数和变量名称清晰编写的代码，这些名称使其意图和函数易于理解。如果做得好，它就是文档。

它可以取代注释和文档完善的代码，但我很少见到它。很多时候，程序员认为他们已经足够好了，但是打倒他们的最好方法是开始问问题。如果他们不得不开始解释太多，那么他们的代码就不够清晰。您不应该阅读代码来了解它的功能。

在某些情况下，这样做会更好。如果代码又小又简单，那么添加文档可能会把事情弄得乱七八糟。

包含算法的代码应该包含注释。大多数时候，即使是最初的程序员也不记得几个月前他们在写一个长函数时到底在想什么。

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

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

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

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

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

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

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.

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

Self documenting code is code that is trivially easy to understand. Variable naming goes a long way to making code self documenting, but i find the best tactic is to break any complicated logic down into tiny little chunks and refactor that information into seperate methods with verbose and informative names. Then your complicated methods become simply a list of steps to be performed. The tiny private helper methods then are documented sufficiently by their own method name and the complicated methods are documented as a sequence of abstract steps to be performed. In practice this strategy cannot always be applied perfectly so comments are still very useful. Plus you should never completely abandon any tool which will help you write code that is easier to understand.

不管纯粹的自文档代码是否可以实现，有一些事情是人们应该做的:

Never have code that is "surprising". Ie. don't use silly macro's to redefine things etc. Don't misuse operator overloading, don't try to be smart on this. Split away code at the right point. Use proper abstractions. Instead of inlining a rolling buffer (a buffer with fixed length, with two pointers that gets items added at one end and removed at the other), use an abstraction with a proper name. Keep function complexity low. If it gets too long or complex, try to split it out into other other functions.

当实现特定的复杂算法时，添加描述算法的文档(或链接)。但在这种情况下，要努力去除不必要的复杂性，增加易读性，因为很容易犯错误。

首先，考虑下面的代码片段:

/**
 * Sets the value of foobar.
 *
 * @foobar is the new vaue of foobar.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

在这个例子中，每3行代码有5行注释。更糟糕的是，注释没有添加任何你在阅读代码时看不到的东西。如果你有10个这样的方法，你可能会得到“注释盲视”，没有注意到一个偏离模式的方法。

当然，更好的版本应该是:

/**
 * The serialization of the foobar object is used to synchronize the qux task.
 * The default value is unique instance, override if needed.
 */
 public void setFoobar(Object foobar) {
     this.foobar = foobar;
 }

不过，对于简单的代码，我更喜欢没有注释。意图和整体组织最好在代码之外的单独文档中解释。