文档样式

Question

从我的一个编程类的教学大纲：“只要能够只读取注释，而无需查看代码，并解释代码的作用，您的文档就足够了。”

有没有人听说过像这样的文档风格？这是一个好习惯吗？看起来对我来说非常热情。

Answer 1

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

1. 适当的和有意义的命名
2. 评论特别困难的算法或复杂的代码
3. 广泛的所有代码文档

适当的文件将使用所有三种方法都适用。

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

所有的代码都应该写出来并记录下来，这样当你在早上三点打标时，由于你的最差的批评者可以理解它，因为生产系统有问题。

与此同时，过多的评论是另一项需要维护的内容，并且在对代码进行更改时与代码保持同步，并且评论是最不可能在变更之下妥善维护的内容。

Answer 2

我有，我自己的低年级工作最初有这样的要求。这可能有点过分，但如果它让人们评论他们的代码，那么我就是为了它。

Answer 3

我会说相反。一个好的文档就是一个代表自己的代码！有些评论倾向于使代码不易读和愉快。如果我们一直对初学者说这​​些话，那么他们就有很大的风险，他们会编写程序，其中代码评论比率会非常低（换句话说，这当然意味着他们已经评论过他们的代码不太好） 。只有在解释了一个不重要的算法或指令的情况下，才能写出评论。剩下的应该留给代码（比如命名你的变量，比如你理解他们的工作）。

Answer 4

这是一个很好的做法。这意味着您可以将代码视为黑盒子，这样可以使整个生活更加简单。我同意这样记录是不是很有趣，但你可以考虑让一位同事帮助你。甚至可能是像技术作家这样的专家。

Answer 5

在上课的背景下，是的。那位教授想知道你的代码背后的意图。除了查看你的代码之外，这位教授没有简单的方法来问这个问题。它还将帮助您将部分任务分成几个可编程的块。

在现实世界中？这取决于。我们将工作记录到我们修改的任何课程，同时提交 - 这是我们记录变更背后意图的好地方。大量的评论需要大量的维护。如果评论解释了实现的原因，并且实现发生了变化，那么该评论也会发生更好的变化。

Answer 6

该指令含糊不清。你应该向你的导师寻求澄清。

有人可能会将该指令解释为意味着您的注释描述了该代码。大学毕业后这不是好习惯。然而 - 这是从经验 - 到分级初学者的工作，这可能是非常有帮助的。你想对那些评分工作有帮助。

另一种解释是，你应该记录你的代码的一部分 - 类，方法，长方法中的代码块可能更好地重构成更小的方法的目的。其中一些示例可以在许多类库中生成的API文档中找到。