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

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

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

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

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

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

我用元注释评论公共或受保护的函数,如果我记得的话,通常会点击私有函数.

我评论为什么存在任何足够复杂的代码块(判断调用).该为什么是重要的组成部分.

我评论如果我编写的代码我认为不是最优的但是我留下来因为我无法找到更聪明的方法,或者我知道我将在稍后进行重构.

我评论提醒自己或其他人缺少功能或代码中没有的要求代码(TODO等).

我评论解释与一个类或一大块代码相关的复杂业务规则.我知道会写几段以确保下一个人/ gal知道为什么我写了一百行.

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

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

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