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

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

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

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

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.

我会扭转局面。

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

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

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

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

你能读懂你写的东西吗?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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