我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
有人曾经说过
1)只对难以理解的代码写注释。 2)尽量不要编写难以理解的代码。
其他回答
好的设计结构有助于指出，有些函数是通用的，有些是随机的业务逻辑，即使你没有评论说“这个函数是通用的”。
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.
还要考虑功能的可跟踪性。当你有了你的手册，那么你应该能够追踪到源代码的特性，并返回更好的可维护性。手册和规范与编程没有太大关系，但它们与软件工程有关。软件越大，需要的工程设计就越多。
我很惊讶居然没有人提出“识字编程”，这是一种由德克萨斯州的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.)你应该读一读。
这是自文档化的代码，包括推理等。即使是一份很好的文件， 其他一切都是写得很好的评论:-)
大多数文档/注释都是为了帮助未来的代码增强者/开发人员，从而使代码可维护。 通常情况下，我们会在稍后的时间回到我们的模块来添加新功能或优化。 在那个时候，通过简单地阅读注释来理解代码要比通过大量的断点来理解代码容易得多。 此外，我宁愿花时间思考新的逻辑，而不是破译现有的。
自我记录代码是愚蠢的。任何在几周、几个月或几年之后不得不重新访问代码的人都知道这一点(对我来说是几天)。(也许推广这个想法的人还很幼稚!?! ! !)
使用有意义的、描述性的数据名称，聪明地分解代码，并给自己留下提示，告诉自己为什么要这么做，这样你的生活就会更丰富、更充实。
尽管……我确实读过一句比尔·盖茨说过的话:“代码就是文档。”
图。
我相信您应该始终努力实现自文档化代码，因为它确实使代码阅读变得更容易。然而，你也必须务实。
例如，我通常为每个类成员添加注释(为此我使用文档注释)。这描述了成员应该做什么，而不是如何做。我发现，当我阅读代码，特别是旧代码时，这有助于我快速记住成员是用来做什么的，我也发现这比阅读代码和解决它更容易，特别是当代码流跳跃相当多的时候。
这只是我的个人观点。我知道很多人在工作时根本没有评论，他们认为这没有问题。然而，我曾经问过某人关于他们六个月前写的一个方法，他们不得不思考几分钟来告诉我它到底是做什么的。如果方法是注释的，这不是问题。
最后，您必须记住，注释和代码一样都是系统的一部分。在重构和更改功能时，还必须更新注释。这是反对使用注释的一个论点，因为如果它们不正确，它们比无用更糟糕。
