代码提交注释的最佳实践

这是我的想法…根据您的特定开发方法,所有这些都可以解释。

• 您应该经常提交,每次提交都只关注一个焦点,因此基于此,注释应该简短并且详细说明提交的焦点是什么。
• 我很喜欢发布 什么 在您的评论中, 为什么? 以及 怎样 在其他地方详细描述(最好是在错误跟踪中)。为什么应该是票,在关闭票时,您应该有一些关于如何解决特定问题的笔记。
• 如果不进行其他处理(例如,trac/svn交互),那么对bug跟踪系统的引用是很好的。这样做的原因是,如果其他开发人员正在寻找关于提交的更多信息,那么他们就可以将其指向正确的方向。
• 不要包含特定的文件名,除非需要非常复杂和详细的修复。即使如此,复杂的细节可能属于bug跟踪和实现说明,而不是版本控制。编辑的文件、差异详细信息等,希望可以包含在版本控制中,我们不想花时间复制这些内容。

考虑到这些想法,我举一个例子提交评论

req3845:更新验证,使用req3831中开发的新regex验证。

简而言之,传达所发生的变化,并为其他人提供某种参考,以便在不追捕你的情况下获得更多信息。

我在每个段落前面加上+-*或!

+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix

我认为您不应该提交关于代码的哪些部分被更改的详细描述,因为这就是为什么每个VC都有不同之处:)

如果您使用错误跟踪系统,请包括相关的票据编号。

您不需要提及更改的文件或您的姓名。源存储库可以自己解决这个问题。描述这些变化也只有在差异不是非常明显的情况下才有意义。

确保您有一个良好的第一行,因为这经常出现在更改历史视图中,并且人们需要通过它来查找内容(例如,bug跟踪票据号应该出现在那里)。

尝试在单个变更集中提交相关的更改(并将不相关的更改拆分为两个提交,即使是对同一个文件)。

我尝试遵循与代码注释相同的规则:

解释 为什么? 而不是 同质光波导 .

IMO评论应包含对该问题的引用(任务追踪器或需求)。版本控制系统已经提供了受影响的文件。除此之外,它应该尽可能短,但仍然可读。

我尝试将修复程序保存在单独的签入中。

我不使用实际的模板,而是一个精神上的模板,就像这样。

问题-开发级别摘要 问题。

问题跟踪程序具有所有的管理细节,并且可以检查代码更改的更改/差异,因此评论是为了让开发人员了解问题的原因/内容。

以下是我看到的成功使用:

• 对错误号或功能ID的引用
• 变更的简要说明。改变了什么。
• 代码审查员(以确保您有一个),除非由签入系统处理。
• 测试人员的名称或运行测试的描述(如果过程太晚并且您特别小心)

我使用的是 Chaosben 上 JEDI Windows API blog .

以便快速查看 对存储库所做的更改,我们 建议写简明扼要 每行以一个开头的注释 这些字符:

• + 如果您添加了功能/功能/
• - 如果您删除了一个功能/功能/错误/错误
• γ 如果你改变了什么

这样做,其他开发人员可能会发现所需的修订版更好。

首先,提交应该解决一个单一的问题(对于逻辑上独立的更改,单独提交)。如果您不知道在提交消息中写什么,或者Comit消息太长,这可能意味着您的提交中有多个独立的更改,您应该将其拆分为较小的项。

我认为提交消息约定 吉特 很有意义:

• 提交消息的第一行应该是简短的描述
• 如果合适,在上述摘要行前面加上子系统前缀,例如“docs”或“contrib:”
• 在下一段或下一段中,描述变化,解释原因和方式

请记住,如果有人需要更改内容的详细信息,他们可能会有所不同。也就是说,我通常只为每个主要更改编写一到两个句子,然后在结尾处添加任何小的修复。

没有什么比简单的英语更严格和快捷的规则了。我尽量用最少的语言解释所做的工作。任何寻找变化历史的人都只想知道特定变化中发生了什么。如果有人想了解更多的细节,那就在代码中。

我接下来要做的第二件事是,如果有任何相关的bug,那么将其插入,或者如果它与任何开发人员任务相关,那么将其与更改关联。

如果由于不同的原因更改了两个文件,那么它们应该处于不同的提交状态。您一次提交多个代码文件的唯一时间是因为它们都属于同一个修复/更改。