关于评论代码的"硬规则"是什么？

Question

我已经看到了其他问题,但我仍然不满意这个主题的涵盖方式.

我想在代码检查中提取一个废弃的列表来检查注释.

我相信人们会说会相互抵消的事情.但是,嘿,也许我们可以为每个阵营建立一个清单.对于那些没有评论的人来说,这个名单会很短:)

Answer 1

我有一个关于评论的简单规则:你的代码应讲述你在做什么的故事; 你的评论应该讲述你为什么这么做的故事.

这样,我确保继承我的代码的任何人都能够理解代码背后的意图.

Answer 2

1. 我用元注释评论公共或受保护的函数,如果我记得的话,通常会点击私有函数.
2. 我评论为什么存在任何足够复杂的代码块(判断调用).该为什么是重要的组成部分.
3. 我评论如果我编写的代码我认为不是最优的但是我留下来因为我无法找到更聪明的方法,或者我知道我将在稍后进行重构.
4. 我评论提醒自己或其他人缺少功能或代码中没有的要求代码(TODO等).
5. 我评论解释与一个类或一大块代码相关的复杂业务规则.我知道会写几段以确保下一个人/ gal知道为什么我写了一百行.

Answer 3

如果评论已过期(与代码不匹配),请将其删除或更新.永远不要留下不准确的评论.

Answer 4

编写尽可能不言自明的可读代码.每当您必须编写太复杂而无法一目了然的代码时,请添加注释.还要添加注释来描述您编写的代码背后的业务目的,以便将来更容易维护/重构它.

Answer 5

文档就像性; 什么时候好,它非常非常好,当它很糟糕时,它总比没有好

Answer 6

您编写的注释可以揭示您的代码质量。无数次我删除了代码中的注释，用更好、更清晰的代码替换它们。为此，我遵循一些反评论规则：

• 如果您的评论仅解释了一行代码，那么您应该让该行代码不言自明，或者将其拆分为更简单的组件。
• 如果您的注释解释了函数中的一段代码，那么您可能应该解释一个新函数。

这些实际上是在两个不同的上下文中重复的相同规则。

我遵循的其他更正常的规则是：

• 使用动态类型语言时，记录重要函数对其参数的期望，以及调用者对返回值的期望。重要的函数是那些将永远有非本地调用者的函数。
• 当您的逻辑由另一个组件的行为决定时，最好记录您对该组件的理解和期望。