Answers:
注释应在上下文中阅读,因此:
对于方法上方或发生某些行为之前的源注释:
// This function does X
function doX() { ... }
对于发生某些行为后的源注释
function doX() {
widget.doY()
// did Y to widget to prepare it for Z
...
}
对于提交消息
功能X已更改
混合示例:
// This function does X
function doX() {
widget.doY()
// did Y to widget to prepare it for Z
....
}
注释是静态的,因此它们应按原样显示程序的状态,而不应按现状显示。要回答您的特定问题,使用过去时更合适。
但是,这种类型的注释更适合您的版本控制系统。版本控制比手动注释在更改跟踪方面做得更好。使用版本控制系统,以当前时态记录文档更合适,因为这些注释在更改提交时适用。但是,两者都可以。
我强烈建议您的代码中唯一的注释应该是理解代码本身所需的内容-目的,业务逻辑和特殊情况。将变更集文档留给您的版本控制系统。如果您不使用VCS,请立即开始。有几种免费的高质量VCS(Subversion,Mercurial,Git等)。
我使用命令式现在时,如下所示:
将“ x”更改为“ y”
这是Git开发人员推荐的:
- 正文应提供有意义的提交消息,该消息:
- 使用命令式现在的时态:“更改”,而不是“更改”或“更改”。
乍一看似乎有些奇怪,但是如果您将提交视为可以执行某些操作的补丁程序,那就更有意义了。(在像Git这样的DVCS中,尤其如此,在该DVCS中,您从其他执行回购的人那里获取变更集。)
如果您使用的是git,则约定使用当前时态,因为使用git工具生成的提交消息(例如,合并)使用当前时态。
注释是(或应该),就像任何书面内容一样,是某种事物的表达,并且它们应仅遵循自然语言中的相同规则(考虑到针对所记录的情况或工件的速记和缩写)。
对当前时态的注释(即“它正在更改”或“它正在更改”)表示正在通过记录算法运行的一条数据受到某种方式的影响。也就是说,它指示代码正在执行或正在处理的数据正在发生什么。
过去式中的注释应指示在注释所驻留的点之前发生的某些事情的断言,前提或后置条件。例如:
输入此代码块之前,输入已被验证
要么
在执行此代码的末尾,数据已写入文件
过去时的注释还可以解释为什么要执行某些操作(此函数执行X和Y来处理旧数据库的问题。)
过去式中的注释表示代码本身已发生更改(即X更改为Y),不应包含在代码中。相反,它们应作为修订注释存在于源代码存储库中。
将来的评论应该指出需要满足或解决的条件,但是由于X或Y的原因,目前还没有完成。例如:
当我们最终迁移数据库时,我们将不得不更改此逻辑
要么
待办事项:尽快,重新审视输入的验证-对于X或Y类型的输入,它可能会失败,可能需要立即执行的大量更改。
对于以后的TODO类型的注释,应存在其他形式的文档,以确保确实进行了此类更改。您想要的最后一件事是时间和空间上迷失的TODO:P
带着一粒盐拿它,但是通常这些是我发表自己的评论时通常遵循的规则。
评论是与人沟通,因此,尽管一致性很重要,但重要的是,当原则本身妨碍良好的沟通时,不要陷入原则中。也就是说,我使用以下伪标准:
描述期望行为的注释采用当下祈使句的形式。
// Calculate the width of the curve at x height.
使用一组全大写的关键字来描述编码中的常见主题(并使其易于搜索):
// NOTE: <This code was written this way for a reason.>
// TODO: <This code is incomplete. Finish it.>
// HACK: <This code was written this way for a reason that you won't like.>
// FIXME: <This code has a known flaw. Fix it.>