代码本身总是对代码功能的最新解释，但在我看来，它很难解释意图，这是注释最重要的方面。如果代码写得很好，我们已经知道代码的功能，我们只需要知道它到底为什么这样做!

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

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

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.

我想他可能想说的是，如果注释解释了代码的功能，那么就应该重写，以明确它的意图。这就是他所说的自文档代码。这通常意味着简单地用描述性函数名将长函数分解成逻辑上的小块。

这并不意味着代码不应该被注释。这意味着注释应该提供代码以这种方式编写的原因。

我认为自记录代码是注释的一个很好的替代品。如果您需要注释来解释代码是如何或为什么是这样的，那么您应该修改函数或变量名以使其更具解释性。这可能取决于编码器是否会用注释或重命名一些变量和函数并重构代码来弥补不足。

但是，它并不能真正取代您的文档，因为文档是您提供给其他人用来解释如何使用您的系统的，而不是它是如何工作的。

编辑:我(可能还有其他所有人)应该有一个数字信号处理(DSP)应用程序应该很好地注释的规定。这主要是因为DSP应用程序本质上是2 for循环，提供了数组的值和添加/乘以/等等所说的值…要更改程序，您需要更改其中一个数组中的值…需要一些评论来说明在这种情况下你在做什么;)

我忘了我从哪学来的，但是:

程序中的每一条评论都像是对读者的道歉。“很抱歉，我的代码太晦涩了，你看了都看不懂。”我们只需要接受我们并不完美，但要努力做到完美，在需要的时候道歉。

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

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

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

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

“自文档化”代码背后的思想是，代码中的实际程序逻辑非常清楚，不仅可以向阅读代码的人解释代码在做什么，还可以向他们解释为什么要这样做。

在我看来，真正的自文档代码的想法是一个神话。代码可以告诉您正在发生的事情背后的逻辑，但它不能解释为什么要以某种方式完成，特别是如果有不止一种方法来解决问题。仅仅因为这个原因，它永远不能取代注释良好的代码。

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

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

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.

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

在我看来，任何代码都应该是自记录的。在良好的、自文档化的代码中，您不必解释每一行，因为每个标识符(变量、方法、类)都有一个明确的语义名称。过多的注释实际上会使代码更难阅读(!)，所以如果您的同事

为每个类、成员、类型和方法and编写文档注释(Doxygen、JavaDoc、XML注释等) 清楚地注释代码中没有自文档化AND的部分 为每个代码块写一个注释来解释意图，或者代码在更高抽象级别上做了什么(例如，找到所有大于10mb的文件，而不是遍历目录中的所有文件，测试文件大小是否大于10mb，如果为真则返回)

在我看来，他的代码和文档都很好。请注意，自文档化的代码并不意味着不应该有注释，而只是不应该有不必要的注释。然而，问题是，通过阅读代码(包括注释和文档注释)应该立即理解代码的功能和原因。如果“自文档化”代码比注释代码需要更长的时间来理解，那么它就不是真正的自文档化。

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.

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

所谓的自文档代码的真正问题在于它传达了它实际做的事情。虽然一些注释可以帮助别人更好地理解代码(例如，算法步骤等)，但它在一定程度上是多余的，我怀疑你能否说服你的同行。

然而，文档中真正重要的是代码中没有直接体现出来的东西:潜在的意图、假设、影响、限制等等。

能够通过快速浏览来确定代码执行X操作比能够确定代码不执行Y操作要容易得多。他必须记录Y…

你可以给他看一个代码的例子，看起来很好，很明显，但实际上并没有覆盖所有的输入基，比如，看看他是否能找到它。

我会扭转局面。

问问自己在他的代码中有什么不理解的，然后让他把这些记录下来。也许你也可以告诉我们一些。

您可能希望向您的同事指出的一件事是，无论他的代码是如何自我记录的，如果考虑并放弃了其他替代方法，那么该信息将丢失，除非他用该信息注释代码。有时，了解考虑了替代方案以及为什么不选择它同样重要，并且代码注释最有可能随着时间的推移而幸存下来。

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

/**
 * 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;
 }

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

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

//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
}

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

既然这是关于注释和代码的，那么让我们来看一些实际的代码。比较下面的典型代码:

float a, b, c; a=9.81; b=5; c= .5*a*(b^2);

到这个显示正在执行的操作的自文档代码:

const float gravitationalForce = 9.81;
float timeInSeconds = 5;
float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);

然后是这个文档代码，它更好地解释了为什么要这样做:

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

最终版本的代码作为文档，不需要注释:

float computeDisplacement(float timeInSeconds) {
    const float gravitationalForce = 9.81;
    float displacement = (1 / 2) * gravitationalForce * (timeInSeconds ^ 2);
    return displacement;
}

下面是一个糟糕评论风格的例子:

const float a = 9.81; //gravitational force
float b = 5; //time in seconds
float c = (1/2)*a*(b^2) //multiply the time and gravity together to get displacement.

在最后一个例子中，当变量应该被描述性地命名时，就会使用注释，当我们可以清楚地看到操作是什么时，就会总结操作的结果。无论如何，我更喜欢自文档化的第二个示例，也许这就是您的朋友所说的自文档化代码。

我会说，这取决于你所做的事情的背景。对我来说，在这种情况下，自编文档的代码可能就足够了，但是详细描述所做事情(在本例中是方程)背后的方法的注释也很有用。

在顺序:

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.

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

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

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

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

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

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

自文档化代码是一种很好的实践，如果操作得当，可以轻松地传达代码的含义，而无需阅读太多注释。特别是在团队中的每个人都很好地理解该领域的情况下。

话虽如此，评论对于新手、测试人员或生成文档/帮助文件都非常有帮助。

自文档化代码+必要的注释将大大有助于跨团队的人员。

This is an excellent question. It traces back to the first programming language that allowed comments, I'm sure. The code certainly should be as self-documenting as possible. Comments that point out the obvious, should be eliminated. Comments that make it easier to understand the intent, purpose, and use of a given method or section of code can be invaluable to those of us dolts that may be less familiar with the language or code in question. Structured comments that allow for the generation of API documentation are a good example. Just don't comment an IF statement that checks to see if a checkbox is checked and tell me that you're checking to see if the checkbox is checked. Restating the obvious in a comment is the worst waste keystrokes in our universe.

//For example, the above text deals with what is a useful comment

首先，很高兴听到您同事的代码实际上比您见过的其他代码更清晰。这意味着他可能不会用“自记录”作为懒得注释代码的借口。

自文档代码是不需要自由文本注释的代码，以便知情的读者理解它在做什么。例如，这段代码是自记录的:

print "Hello, World!"

这也是:

factorial n = product [1..n]

这也是:

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 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.

有人曾经说过

1)只对难以理解的代码写注释。 2)尽量不要编写难以理解的代码。

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

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

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

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

Etc.

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

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

在编写数学代码时，我有时发现写一篇类似文章的长注释很有用，解释数学、代码使用的符号约定以及它们是如何组合在一起的。我们在这里讨论的是数百行文档。

我试着让我的代码尽可能地自文档化，但当我几个月后重新开始工作时，我确实需要阅读解释，以免把它弄得乱七八糟。

当然，这种极端的措施在大多数情况下是不必要的。我认为这个故事的寓意是:不同的代码需要不同数量的文档。有些代码可以写得很清楚，以至于不需要注释——所以要写得清楚，不要在那里使用注释!

但是很多代码确实需要注释才能有意义，所以写得越清楚越好，然后使用尽可能多的注释……

为什么代码之外的额外注释可能会更清晰，原因如下:

您正在查看的代码是自动生成的，因此对代码的任何编辑都可能在下次编译项目时失败 一个不太直接的实现被用来换取性能的提高(展开循环，为昂贵的计算创建查找表，等等)。

这将完全取决于团队在文档中的价值。我建议记录为什么/意图而不是如何是重要的，这并不总是在自记录代码中捕获。获取/设置没有这些是显而易见的-但计算，检索等一些为什么应该表达。

如果你来自不同的国家，你也要意识到你的团队中的差异。措辞上的差异会影响到方法的命名:

BisectionSearch

BinarySearch

二进制斩

这三种方法都是由在3个不同大洲接受过培训的开发人员提供的。只有通过阅读描述算法的注释，我们才能识别库中的重复。

如果没有注释，代码就不完全清晰，那么还有改进代码的空间。

我并不是说“不要评论不清楚的代码”。我说的是“让你的代码清晰”。

如果你最终让你的代码在某种程度上不清楚，那么使用注释来弥补。

自我记录代码是愚蠢的。任何在几周、几个月或几年之后不得不重新访问代码的人都知道这一点(对我来说是几天)。(也许推广这个想法的人还很幼稚!?! ! !)

使用有意义的、描述性的数据名称，聪明地分解代码，并给自己留下提示，告诉自己为什么要这么做，这样你的生活就会更丰富、更充实。

尽管……我确实读过一句比尔·盖茨说过的话:“代码就是文档。”

图。

我认为，质疑某一行代码是否具有自文档性是有意义的，但最终，如果你不理解一段代码的结构和功能，那么大多数时候注释是没有用的。以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);

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

我很惊讶居然没有人提出“识字编程”，这是一种由德克萨斯州的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.)你应该读一读。

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

来自非评论阵营的一些观点。

“注释良好”(冗长)的代码更难阅读和理解。首先，有更多的文本需要扫描。它增加了理解CodeBase的认知努力——非功能性文本占用了屏幕上可以用来显示代码的空间。

注释的另一个大问题是它们不可靠——尤其是在旧的代码库中，注释腐烂比位腐烂发生得更快。

当然，还有写评论的工作。除了偶尔的一行注释之外，每次我开始注释代码时，都会有两种负罪感

这个信息需要在整个支持文档中 我需要清理我的代码

对我来说，阅读需要注释的代码就像阅读我不懂的语言的文本。我看到声明，但我不明白它是做什么的，也不明白为什么——我不得不看注释。我读了一个短语，我需要查字典来理解它的意思。

编写自记录其功能的代码通常很容易。要告诉你为什么这样做注释更合适，但即使在这里代码也可以更好。如果您在抽象的每一个层次上都理解您的系统，那么您应该尝试像这样组织代码

public Result whatYouWantToDo(){
  howYouDoItStep1();
  howYouDoItStep2();
  return resultOfWhatYouHavDone;
}

方法名反映了你的意图，方法体解释了你如何实现你的目标。 无论如何，你不能从书名中看出整本书，所以你的系统的主要抽象仍然必须被记录下来，还有复杂的算法、非平凡的方法契约和工件。

If the code that your colleague produc is really self-documented - lucky you and him. If you think that your colleagues code needs comments - it needs. Just open the most non-trivial place in it, read it once and see if you understood everything or not. If the code is self-documented - then you should. If not - ask your colleague a question about it, after he gives you an answer ask why that answer was not documented in comments or code beforehand. He can claim that code is self-document for such smart person as him, but he anyway has to respect other team members - if your tasks require understanding of his code and his code does not explain to you everything you need to understand - it needs comments.

我认为——就像你们中的许多人一样——要真正实现自文档化，代码需要显示某种形式的意图。但是我很惊讶没有人提到BDD——行为驱动开发。这个想法的一部分是，你有自动化的测试(代码)来解释你的代码的意图，这是很难明显的。

Good domain modeling 
+ good names (variabes, methods, classes) 
+ code examples (unit tests from use cases) 
= self documenting software 

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

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.

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

这里的输入似乎非常复杂:)

我使用伪代码编程过程进行新的开发，这实际上使我的代码自文档化。我只在写新代码时才开始写伪代码，然后在上面扩展。我不是说这是最佳实践或类似的东西，我只是强调一个我认为有用的技巧，如果你知道你的代码需要大量的文档，如果它要交给第三方，审查者等等……它偶尔也会在我还没写一行代码的时候就给我指出一些问题。

' check database is available
  ' if it is then allow the procedure
  ' if it isnt roll back and tidy up 
' move onto something else

变成了;

' check database is available
  if checkDBStateResult(currentDB) = Open then 
     ' if it is then allow the procedure
          proc.Ok = True 
  else
     ' if it isnt roll back
          proc.Ok = False
          CleanUp()
  end if

大多数文档/注释都是为了帮助未来的代码增强者/开发人员，从而使代码可维护。 通常情况下，我们会在稍后的时间回到我们的模块来添加新功能或优化。 在那个时候，通过简单地阅读注释来理解代码要比通过大量的断点来理解代码容易得多。 此外，我宁愿花时间思考新的逻辑，而不是破译现有的。

当你阅读“自文档代码”时， 你看它在做什么， 但你不能总是猜测它为什么会以那种特定的方式运行。

有大量的非编程约束 比如业务逻辑、安全性、用户需求等。

当您进行维护时，这些背景信息变得非常重要。

只是我的一小撮盐……

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

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

已经提出的观点是，评论应该捕捉意图，但我想再深入一点。

我认为对于任何一类问题，都有一个理想的(或几乎是这样的)词汇和语法来描述它，如果你只是让遇到这类问题的人来描述它们(假设那个人能清晰地思考)，你就能看到它。

如果词汇和语法可以很容易地(通过定义类、方法等)映射到计算机语言的代码上，那么这些代码可以是自文档化的。此外，IMO还创建了一种特定于领域的语言。(这就是我对“陈述性”的粗略定义。)

如果不能实现这个理想，如果问题不能直接映射到计算机代码上，那么就需要将两者联系起来。在我看来，这就是评论的目的。

这样，当问题发生变化时，您就可以找到相应的代码部分进行更改。

编辑:顺便说一下，我并不支持OOP方法论，即每个名词都变成一个类，每个动词都变成一个方法。我已经看过足够多的臃肿软件了。

对于许多有效的答案，我想再提供一个观点:

什么是源代码?什么是编程语言?

机器不需要源代码。他们很高兴运行组装。编程语言是为了我们的利益。我们不想写汇编。我们需要理解我们在写什么。编程就是写代码。

你能读懂你写的东西吗?

源代码不是用人类语言编写的。它已经被尝试过(例如FORTRAN)，但并不完全成功。

源代码不能有歧义。这就是为什么我们必须在其中加入比文本更多的结构。文本只适用于上下文，当我们使用文本时，我们认为这是理所当然的。源代码中的上下文总是存在的。想想c#中的“使用”。

大多数编程语言都有冗余，这样编译器就能在我们不连贯的时候发现我们。其他语言使用更多的推理，并试图消除冗余。

类型名、方法名和变量名在计算机中是不需要的。它们是供我们参考的。编译器不理解语义，这是我们要用的。

编程语言是人与机器之间的语言桥梁。它必须对我们来说是可写的，对他们来说是可读的。次要要求是它应该对我们来说是可读的。如果我们擅长语义，并且擅长构建代码，那么即使对我们来说，源代码也应该很容易阅读。最好的代码不需要注释。

但是复杂性潜伏在每个项目中，您总是需要决定将复杂性放在哪里，以及吞下哪只骆驼。这些是使用注释的地方。

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

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.

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

区别在于“什么”和“如何”。

您应该记录一个例程做了什么。 你不应该记录它是如何做到的，除非特殊情况(例如，参考一篇特定的算法论文)。这应该是自我记录的。

在我工作的一家公司里，一个程序员把下面的文字粘在了她的显示器上。

“就像维护代码的人是一个知道你住在哪里的杀人狂一样，记录你的代码。”