如何避免落入不注释代码的陷阱？

Question

我做一个项目已经有一个月了。我对代码非常熟悉，并且理解它的程度，我觉得它是如此容易理解，以至于大多数方法在我看来不需要评论。我不知道是因为它实际上是简单的代码，还是我只是很好地实践了它的运行方式。如何划分简单代码和需要注释的代码之间的界限？

Answer 1

如果代码是简单的，那么应该很容易理解。只要这样做，在语法上完全正确的句子，使用一致和适当的命名。

在某些遗漏中，您可能会发现编写一个好的文档头是很困难的，或者您会发现一种比它应该做的更多的方法。

认真对待文档化会带来更好的代码。它通过强迫你用一种不同的语言表达你的逻辑来加强你的设计。如果设计仍然有意义，当你完成时，你应该是好的。如果它开始感觉不对，或者你很难找到一个清晰的描述，你仍然有一些工作要做。

最后，但并非最不重要的是，它将使您的代码更容易访问，如果不是别人对您自己忘记了它做了什么。

如果您用C#.NET编写，请查看StyleCop。我喜欢这样。但任何语言都应该有相似之处。

Answer 2

我也有同样的处境。在编写了一段时间的代码之后，您就非常熟悉它了。你知道它是怎么工作的。但是想象一下，如果你第一次读到别人写的东西。注释将使代码更容易阅读。我通常喜欢做的(而且我的经验非常有限)是对算法和函数做出更高层次的评论，解释它们通常在做什么。然后，如果有一行代码做一些更复杂的事情，比如某种计算或什么的，那么包括一条注释来解释正在发生的事情。希望这能有所帮助。

Answer 3

很简单。始终注释并放置一个自动匹配的检查，以防止代码没有注释被签入。

高级程序员可能开始跳过与函数或变量名称相同的注释。