我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。
我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。
帮我理解一下他的观点。
什么是自文档代码 它真的能取代注释良好和文档化的代码吗 在某些情况下，它是否比有良好文档和注释的代码更好 是否存在代码不可能在没有注释的情况下自文档化的例子
也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。
这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。
另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。
当前回答
大多数文档/注释都是为了帮助未来的代码增强者/开发人员，从而使代码可维护。 通常情况下，我们会在稍后的时间回到我们的模块来添加新功能或优化。 在那个时候，通过简单地阅读注释来理解代码要比通过大量的断点来理解代码容易得多。 此外，我宁愿花时间思考新的逻辑，而不是破译现有的。
其他回答
自我记录代码是“DRY”(不要重复自己)的一个很好的例子。不要在注释中重复代码本身中的信息。
与其解释变量的用途，不如重命名变量。
与其解释一个简短的代码片段做什么，不如将其提取到一个方法中并给它一个描述性的名称(可能是注释文本的缩短版本)。
与其解释一个复杂的测试做什么，不如把它也提取到一个方法中，并给它起个好名字。
Etc.
在此之后，您将得到不需要太多解释的代码，它可以自行解释，因此您应该删除代码中只是重复信息的注释。
这并不意味着你完全没有注释，有一些信息你不能放入代码中，比如关于意图的信息(“为什么”)。在理想的情况下，代码和注释相互补充，每个注释都增加了独特的解释价值，而不会重复另一个注释中的信息。
我忘了我从哪学来的，但是:
程序中的每一条评论都像是对读者的道歉。“很抱歉，我的代码太晦涩了，你看了都看不懂。”我们只需要接受我们并不完美，但要努力做到完美，在需要的时候道歉。
自我记录代码是愚蠢的。任何在几周、几个月或几年之后不得不重新访问代码的人都知道这一点(对我来说是几天)。(也许推广这个想法的人还很幼稚!?! ! !)
使用有意义的、描述性的数据名称，聪明地分解代码，并给自己留下提示，告诉自己为什么要这么做，这样你的生活就会更丰富、更充实。
尽管……我确实读过一句比尔·盖茨说过的话:“代码就是文档。”
图。
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.
我很惊讶居然没有人提出“识字编程”，这是一种由德克萨斯州的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.)你应该读一读。
这是自文档化的代码，包括推理等。即使是一份很好的文件， 其他一切都是写得很好的评论:-)
