文档样式

Question

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

你们有没有听说过这样的文档风格？这是一个好习惯吗？对我来说似乎非常过分热心。

Answer 1

我会反过来说。一个好的文档是一个能说明问题的代码！有些评论倾向于使代码不那么易读和愉快。如果我们一直对初学者说这​​个，那么他们就会编写程序，其中代码与评论的比例非常低（换句话说，它肯定意味着他们已经过度评论了他们的代码并不是那么好）。 。注释应该只写，并且只有在它解释了非平凡的算法或指令时。其余的应留给代码（比如命名你的变量，比如你了解他们的工作）。

Answer 2

代码应易于遵循。这可以通过多种方式实现：

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

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

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

所有代码都应该被编写和记录，以便当他在早上三点钟的标注时因为生产系统出现问题而被最糟糕的贬损者理解。

同时，过多的注释是另一个要维护的项目，并且在对代码进行更改时与代码保持同步，并且注释是最不可能在更改下正确维护的项目。

Answer 3

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

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

Answer 4

我有，我自己的研究生工作最初有这样的要求。它可能有点过于热心，但如果它让人们评论他们的代码，那么我就是为了它。

Answer 5

这是一个很好的做法。这意味着您可以将代码视为黑盒子，这使得生活更加容易。我同意这样的记录并不好玩，但你可以考虑让同事帮助你。也许甚至像技术作家这样的专家。

Answer 6

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

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

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