写评论的初学者指南？

是否有针对初学者的明确代码编写注释指南？

理想情况下，它将涵盖何时（不应该）使用注释以及应包含哪些注释。

这个答案：

不要评论您正在做什么，但为什么要这样做。

WHAT由干净，可读和简单的代码处理，并通过适当选择变量名称来支持它。注释显示了代码本身无法（或很难）显示的更高层次的结构。

接近，但是对于没有经验的程序员来说，这有点简洁（我认为在几个示例和极端情况的基础上进行扩展非常好）。

更新：除了这里的答案，我认为这个答案对另一个问题也非常重要。

您应该意识到评论的最大弱点：它们变得陈旧。也就是说，随着代码的更改，开发人员很少更新注释以使其与代码保持同步。这意味着您永远无法信任他们，而最终仍会阅读代码。由于这个原因，您的代码应该是自我记录的。您应该以这样的方式选择函数和变量名：代码看起来像散文。

因此，请勿记录该代码在做什么。自文档代码应注意这一点。记录为什么要这样做。WHY通常与业务规则相关或与体系结构相关，并且不会经常更改并且在WHAT上会过时。记录边缘情况。记录例外。记录设计决策。而且最重要的是记录您曾经考虑过但决定不执行的那些设计决策（并记录为什么您决定不使用它们）。

您应该阅读Robert C. Martin的Clean Code书。很好地解释了，如果您需要注释，很可能您编码不正确。理想情况下，您的代码应为“自我注释”。Clean Coder书解释了如何执行此操作，因此不需要注释，并且很好地描述了在必要的情况下如何进行注释。（例如解释一个复杂的数学公式）

如前所述，Code Complete有各种编写注释的准则。简而言之，它是PDL，可以总结为：

1. 描述您的意图，而不是代码在做什么。除非使用一些技巧或使用自定义实现，否则请避免描述实现细节。例如，使用移位位进行除法，使用指针算法访问类成员或对某些池对象使用自定义内存分配器。

2. 首先编写伪代码（即注释），然后在描述完例程/方法/函数后再编写真实代码。所使用的语言是高级的但特定的，因此它可能很冗长

3. 即使在编写代码之前，也要先了解一下代码的功能

4. 使注释与实际代码尽可能接近

目的是避免冗长的，可能不合时宜的不相关注释，而要使注释反映代码的意图和目的。使用高级伪代码还有助于在编写实现之前阐明您的想法。

GameDev.net上有一个链接[解释了PDL] [1]，以防您不想找本书。

我只遵循一个简单且通用的原则：您的注释不应说明代码在做什么，而应说明为什么这样做。Martin Fowler的 文章和有关重构和代码的书完整的书包含大量信息，但是令人遗憾的是，据我所知，它不是摘要形式。

我的建议是编写一些没有任何注释的代码，然后放弃它。一年后再回来阅读。您不容易理解的部分是您应该评论的部分。

我非常喜欢Evan Todd如何总结他对仅有的有用评论类别的观点（引用他的博客）：

• 评论解释原因，而不是原因。这些是最有用的。
• 用几句话来解释下面的巨大代码的功能。这些对于导航和阅读很有用。
• 数据结构声明中的注释，解释每个字段的含义。这些通常是不必要的，但有时无法将概念直观地映射到内存，并且必须使用注释来描述该映射。