文档风格

Question

从我的一门编程课程的教学大纲中可以看出：“如果可以只读注释，而不看代码，并解释代码的作用，那么您的文档就足够了。”

你们有没有听说过这样的文档风格？这是一个很好的实践吗？在我看来太过狂热了。

Answer 1

代码应该很容易理解。这可以通过多种方式来实现：

1. 有关特别困难的算法或复杂代码的适当且有意义的naming
2. commenting

所有代码的广泛文档

适当的文档将在适当的情况下使用所有这三种方法。

然而，当代码的受众主要试图理解代码并评估对概念的理解时-即在学术背景下，第三种可能是非常可取的。

所有的代码都应该被编写并记录下来，这样你最坏的批评者就能理解它，当他凌晨三点在callout上时，因为生产系统有问题。

同时，过多的注释是另一个需要维护的项目，并且在代码发生更改时与代码保持同步，而注释是最不可能在更改后得到适当维护的项目。

Answer 2

我会说相反的话。一个好的文档是一段不言而喻的代码！一些注释可能会降低代码的可读性和趣味性。如果我们一直这样对初学者说，他们很有可能会写出代码与注释的比率非常非常低的程序(换句话说，这肯定意味着他们过度注释了并不是很好的代码)。注释应该只写在解释非平凡的算法或指令的情况下。其余的应该留给代码(就像命名你的变量，比如你理解他们的工作)。

Answer 3

在类的上下文中，是的。那个教授想知道你在代码背后的意图。除了看你的代码，那个教授没有简单的方法来问这个问题。它还将帮助你将任务的一部分分割成可编程的小块。

在真实的世界见面?那得看情况。我们在提交时将工作记录到我们修改的任何类中--这是我们记录更改背后的意图的好地方。大量的评论需要大量的维护。如果注释解释了实现的原因，并且实现发生了变化，那么注释最好也发生变化。