什么是自文档化代码?它能取代文档化良好的代码吗?

我有一个同事，他坚持认为他的代码不需要注释，这是“自文档”。

我已经审阅了他的代码，虽然它比我看到的其他人编写的代码更清晰，但我仍然不同意自文档化代码与经过注释和文档化的代码一样完整和有用。

帮我理解一下他的观点。

什么是自文档代码它真的能取代注释良好和文档化的代码吗在某些情况下，它是否比有良好文档和注释的代码更好是否存在代码不可能在没有注释的情况下自文档化的例子

也许这只是我自身的局限性，但我看不出这怎么能成为一种好的练习。

这并不是一个争论——请不要提出为什么注释良好并有文档记录的代码是高优先级的原因——有很多资源都表明了这一点，但它们对我的同行来说并没有说服力。我认为我需要更全面地了解他的观点，才能说服他。如果你有必要，可以提出一个新的问题，但不要在这里争论。

另外，那些反对自我记录代码的人——这主要是为了帮助我理解自我记录代码传播者的观点(即积极的方面)。

当前回答

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

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

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.

2008-10-17 02:14:53

其他回答

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

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

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

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

Etc.

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

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

2008-10-16 17:57:22

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

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