版本控制注释-过去或现在时[关闭]


12

对于版本控制注释,其他用户会做什么/推荐吗?过去或现在时?

  • x 更改为y。
  • 要么
  • x 更改为y。

27
您不是在说“版本控制检查注释”吗?我从不添加注释来记录实际代码中的更改。它使它杂乱无章。
JohnFx 2011年

1
我真的很困惑-如果@JohnFx是正确的,那么这是一个完全不同的问题。我个人不明白为什么@Robert不能在源代码中表示注释。
Armand

仅供参考:我的意思是
签到

抱歉-为了消除混乱,我的意思是版本控制注释而不是源代码中的注释。问题已更新。
罗伯特·W

Answers:


19

注释应在上下文中阅读,因此:

当下

对于方法上方或发生某些行为之前的源注释:

// 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
    ....
}

注意:我认为上面代码中的所有注释都是多余的,但不一定是不平凡的示例。
阿曼德

7
现在问题已经变了,这个答案有点离题了。
Armand

22

过去 -因为将来任何人阅读它都会引用过去所做的更改。

用“ Changing”(更改)这样的字眼意味着您当前正在进行更改,并且代码可能未完成。

注意:就个人而言,我仅在发生重大变化时才添加更改注释。


10

注释是静态的,因此它们应按原样显示程序的状态,而不应按现状显示。要回答您的特定问题,使用过去时更合适。

但是,这种类型的注释更适合您的版本控制系统。版本控制比手动注释在更改跟踪方面做得更好。使用版本控制系统,以当前时态记录文档更合适,因为这些注释在更改提交时适用。但是,两者都可以。

我强烈建议您的代码中唯一的注释应该是理解代码本身所需的内容-目的,业务逻辑和特殊情况。将变更集文档留给您的版本控制系统。如果您不使用VCS,请立即开始。有几种免费的高质量VCS(Subversion,Mercurial,Git等)。


3
+1,尽管我认为版本控制注释也应该使用过去式。:-)
埃里克·金

拥有一个单独的变更日志文件还不错。将提交的评论隔离到那里不会有太大的伤害,但是在每个文件上都喷上它们只是痛苦的声音。
Donal Fellows

提交消息可以任意选择。我倾向于将其视为因为当时提交的原因而采取的当前行动。归根结底,这是一个英语领域,不要乱发可能是可以的。它不像“吃,
嫩芽

10

我使用命令式现在时,如下所示:

将“ x”更改为“ y”

这是Git开发人员推荐的:

  • 正文应提供有意义的提交消息,该消息:
    • 使用命令式现在的时态:“更改”,而不是“更改”或“更改”。

乍一看似乎有些奇怪,但是如果您将提交视为可以执行某些操作的补丁程序,那就更有意义了。(在像Git这样的DVCS中,尤其如此,在该DVCS中,您从其他执行回购的人那里获取变更集。)


1
我同意一开始它确实很奇怪,将其视为补丁绝对是正确的方法。我一直在做的一件事是在读出提交信息之前先在脑海中背诵“此补丁将”。这是从问自己“我在此补丁中做了什么?”的切换。(修复线程错误)询问自己“此修补程序将做什么?” (修复线程错误)。
Nick Knowlson

5

没关系;我认为这是个人风格和偏好。根据几乎所有内容,请与自己和其他意见保持一致


2

代码注释应该自然阅读。

如果您正在阅读对自己说“此代码正在执行X”的代码,则应以现在时形式编写注释,因为这可能是当时阅读该代码的人也会想到的。如果对方有你在一个特定的点会想“这个代码 X”,那么它应该是过去时。最后,归结为个人喜好,除非出于某种原因您处于如何注释代码的准则下(例如,针对团队项目或针对班级等)。


1

如果您使用的是git,则约定使用当前时态,因为使用git工具生成的提交消息(例如,合并)使用当前时态。


1

您应该使用过去时。

原因是您正在回答这个提交实现了什么问题可以将其视为告诉VCS您做了什么:

提交123
将XYZ更改为ABC

举个反例,使用未来时态听起来就像您要别人去做:

提交123将
XYZ更改为ABC

并使用当前时态听起来好像您已经完成一半了:

提交123
更改XYZ以执行ABC


0

使用现在时:“将X更改为Y”,几乎就像是待办事项清单中的一项一样。

通常,就像编剧一样,避免使用动词,例如“ to be”和“ is”。例如,不是“他在走路”,而是“他在走路”。

但是在这个特定示例中(如果您是在谈论代码注释,而不是签入注释),我相信“将X更改为Y”是一个糟糕的注释。它不添加任何新信息,并且如果代码要更改,它甚至可能是错误的。最好将代码提取到方法(或类)中,然后记录该方法。如果足够清楚,则只需一个好的方法名称就足够了。

说到这,对于记录方法,您可以使用将来时,例如:“如果提供的数字为负,abs则将返回数字的大小。”


0

注释是(或应该),就像任何书面内容一样,是某种事物的表达,并且它们应仅遵循自然语言中的相同规则(考虑到针对所记录的情况或工件的速记和缩写)。

对当前时态的注释(即“它正在更改”或“它正在更改”)表示正在通过记录算法运行的一条数据受到某种方式的影响。也就是说,它指示代码正在执行或正在处理的数据正在发生什么。

过去式中的注释应指示在注释所驻留的点之前发生的某些事情的断言,前提或后置条件。例如:

输入此代码块之前,输入已被验证

要么

在执行此代码的末尾,数据已写入文件

过去时的注释还可以解释为什么要执行某些操作(此函数执行X和Y来处理旧数据库的问题。

过去式中的注释表示代码本身已发生更改(即X更改为Y),不应包含在代码中。相反,它们应作为修订注释存在于源代码存储库中。

将来的评论应该指出需要满足或解决的条件,但是由于X或Y的原因,目前还没有完成。例如:

当我们最终迁移数据库时,我们将不得不更改此逻辑

要么

待办事项:尽快,重新审视输入的验证-对于X或Y类型的输入,它可能会失败,可能需要立即执行的大量更改。

对于以后的TODO类型的注释,应存在其他形式的文档,以确保确实进行了此类更改。您想要的最后一件事是时间和空间上迷失的TODO:P

带着一粒盐拿它,但是通常这些是我发表自己的评论时通常遵循的规则。


0

评论是与人沟通,因此,尽管一致性很重要,但重要的是,当原则本身妨碍良好的沟通时,不要陷入原则中。也就是说,我使用以下伪标准:

  • 描述期望行为的注释采用当下祈使句的形式。

    // 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.>
    
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.