What template do you use for comments on code commit?
您对代码提交的评论使用了什么模板?
One example of a template is:
模板的一个示例是:
- (change 1): (source file 1.1, 1.2): (details of change made), (why)
- (change 2): (source file 2.1): (details of change made), (why)
(更改1):(源文件1.1,1.2):(更改的详细信息),(为什么)
(更改2):(源文件2.1):(更改的详细信息),(为什么)
Ideally each change should be mapped to an issue in the issue tracker. Is this template alright?
理想情况下,每个更改都应映射到问题跟踪器中的问题。这个模板好吗?
11 个解决方案
#1
Here are my thoughts... all these will be open to interpretation depending on your particular development methodologies.
以下是我的想法......所有这些都可以根据您的特定开发方法进行解释。
- You should be committing fairly often, with a single focus for every commit, so based on that, comments should be short and detail what the focus of the commit was.
- I'm a fan of posting the what in your comment, with the why and the how being detailed elsewhere (ideally in your bug tracking). The why should be the ticket, and upon closing the ticket, you should have some kind of note about how that particular issue was addressed.
- A reference to your bug tracking system is good if it isn't handled otherwise (TRAC/SVN interaction, for example). The reason for this is to point other developers in the right direction if they're looking for more information on the commit.
- Don't include specific file names unless the fix really complex and detail is needed. Even still, complex details probably belong in bug tracking with your implementation notes, not in version control. Files edited, diff details, etc, should hopefully be included with version control, and we don't want to spend time duplicating this.
您应该经常提交,每次提交只需一个焦点,因此基于此,注释应该简短并详细说明提交的重点。
我很喜欢在评论中发布内容,以及为什么以及如何在其他地方详细说明(最好是在您的错误跟踪中)。为什么应该是机票,并在关闭机票时,你应该有一些关于如何解决这个特定问题的说明。
如果不以其他方式处理(例如TRAC / SVN交互),则对您的错误跟踪系统的引用是好的。这样做的原因是,如果他们正在寻找有关提交的更多信息,则指向其他开发人员正确的方向。
除非需要修复非常复杂和详细,否则不要包含特定的文件名。即便如此,复杂的细节可能属于您的实施说明的错误跟踪,而不是版本控制。编辑的文件,差异细节等应该包含在版本控制中,我们不想花时间复制它。
Given these ideas, an example commit comment for me would be something like
鉴于这些想法,我的一个示例提交评论将是类似的
Req3845: Updated validation to use the new RegEx validation developed in Req3831.
Req3845:更新了验证,以使用Req3831中开发的新RegEx验证。
Short, communicates what was changed, and provides some kind of reference for others to get more info without hunting you down.
简而言之,传达改变的内容,并为其他人提供某种参考,以获取更多信息而不会让你失望。
#2
I prefix each paragraph with + - * or !
我在每个段落前加上+ - *或!
+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix
I don't think you should commit detailed description about what parts of the code are changed, because that's why every VC has diff :)
我不认为你应该提交有关代码的哪些部分被更改的详细描述,因为这就是为什么每个VC都有差异:)
#3
If you use a bug tracking system, include relevant ticket numbers.
如果您使用错误跟踪系统,请包含相关的票号。
You do not need to mention changed files, or your name. The source repository can figure that out by itself. Describing the changes also only makes sense if it is not non-trivially obvious from the diff.
您无需提及已更改的文件或您的姓名。源存储库可以自己解决这个问题。描述这些变化也只有在差异不明显的情况下才有意义。
Make sure you have a good first line, because this frequently appears in the change history view, and people need to find things by this (the bug tracking ticket number should go there, for example).
确保你有一个好的第一行,因为这经常出现在更改历史记录视图中,并且人们需要通过此查找内容(例如,错误跟踪票号应该去那里)。
Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).
尝试在单个变更集中提交相关更改(并将不相关的更改拆分为两个提交,即使是同一个文件)。
#4
I try to follow the same rule as for code comments:
我尝试遵循与代码注释相同的规则:
Explain the WHY, not the HOW.
解释为什么,而不是如何。
IMO a comment should contain a reference to the issue (task tracker, or requirement). Which files are affected is already available from the version control system. Apart from that, it should be as short as possible, but still readable.
IMO评论应包含对问题的引用(任务跟踪器或要求)。版本控制系统已提供受影响的文件。除此之外,它应该尽可能短,但仍然可读。
#5
I try to keep my fixes in separate check-ins.
我尝试将我的修复程序保存在单独的签入中。
I don't use an actual template, but a mental one, and it's like this.
我不使用实际模板,而是使用心理模板,就像这样。
Issue - dev level summary of issue.
问题 - 开发级别的问题摘要。
The issue tracker has all the management details, and the changes/diffs can be reviewed for code changes, so the comment is for dev's to understand the why/what of the issue.
问题跟踪器具有所有管理详细信息,并且可以检查更改/差异以进行代码更改,因此注释可供开发人员了解问题的原因/内容。
#6
Here's what I've seen used successfully:
这是我见过的成功用法:
- Reference to bug number or feature ID
- Brief description of the change. What was changed.
- Code reviewer (to ensure you have one) unless handled by the checkin system.
- Name of tester or description of which tests were run (if late in the process and you are being extra careful)
引用错误号或功能ID
变化的简要说明。改变了什么。
除非由签入系统处理,否则代码审查员(确保您拥有)。
测试人员的名称或运行测试的描述(如果在过程的后期,你要特别小心)
#7
I use the simple technique described by Chaosben on the JEDI Windows API blog.
我在JEDI Windows API博客上使用Chaosben描述的简单技术。
In order to get a fast view on the changes made to a repository, we suggest to write brief concise comments starting each line with one of these chars:
为了快速查看对存储库所做的更改,我们建议使用以下其中一个字符开始每行写简短的简明注释:
- + if you added a feature/function/…
+如果你添加了一个功能/功能/ ...
- - if you removed a feature/function/bug/…
- 如果你删除了一个功能/功能/ bug / ...
- # if you changed something
#如果你改变了什么
Doing it this way, other developers may find the desired revision much better.
这样做,其他开发人员可以更好地找到所需的修订版。
#8
First, commits should solve one single problem (separate commits for logically separate changes). If you don't know what to write in the commit message, or the comit message is too long it might mean that you have multiple independent changes in your commit, and you should split it into smaller items.
首先,提交应该解决一个单独的问题(单独提交逻辑上单独的更改)。如果您不知道在提交消息中写什么,或者comit消息太长,则可能意味着您在提交中有多个独立更改,并且您应该将其拆分为更小的项。
I think that commit message conventions expected and used by git makes much sense:
我认为git期望和使用的提交消息约定很有意义:
- The first line of commit message should be a short description
- If appropriate, prefix mentioned above summary line with subsystem prefix, e.g. "docs:" or "contrib:"
- In next paragraph or paragraphs describe the change, explaining why's and how's
提交消息的第一行应该是简短描述
如果合适,前面提到的前缀与子系统前缀,例如, “docs:”或“contrib:”
在下一段或段落中描述变化,解释原因和方法
#9
Keep in mind that if someone needs details of what changed, they can get a diff. That said, I just usually write a sentence or two for each major change, and then lump any minor fixes at the end.
请记住,如果有人需要更改内容的详细信息,他们可以获得差异。也就是说,我通常只是为每个重大变化写一两句话,然后在最后将任何小修正结果。
#10
There is no hard and fast rule as its plain english. I try to explain the work done in minimum words possible. Anybody looking for history of changes just want to know what happened in a particular change. If anybody is after more details then its there in the code.
它的简单英语没有硬性规定。我试着用最少的话来解释所做的工作。任何寻找变化历史的人都只想知道特定变化中发生了什么。如果有人在追踪更多细节,那么它就在代码中。
Second thing I follow is if there is any bug associated then stick that in or if its related to any dev task then associate that with the change.
我遵循的第二件事是,如果有任何相关的错误,那么坚持或如果它与任何开发任务相关,然后将其与更改相关联。
#11
If two files were changed for different reasons, they should be in different commits The only time you should commit more than one code file at a time is because they all belong to the same fix/change
如果由于不同的原因更改了两个文件,它们应该在不同的提交中每次只提交多个代码文件是因为它们都属于同一个修复/更改
#1
Here are my thoughts... all these will be open to interpretation depending on your particular development methodologies.
以下是我的想法......所有这些都可以根据您的特定开发方法进行解释。
- You should be committing fairly often, with a single focus for every commit, so based on that, comments should be short and detail what the focus of the commit was.
- I'm a fan of posting the what in your comment, with the why and the how being detailed elsewhere (ideally in your bug tracking). The why should be the ticket, and upon closing the ticket, you should have some kind of note about how that particular issue was addressed.
- A reference to your bug tracking system is good if it isn't handled otherwise (TRAC/SVN interaction, for example). The reason for this is to point other developers in the right direction if they're looking for more information on the commit.
- Don't include specific file names unless the fix really complex and detail is needed. Even still, complex details probably belong in bug tracking with your implementation notes, not in version control. Files edited, diff details, etc, should hopefully be included with version control, and we don't want to spend time duplicating this.
您应该经常提交,每次提交只需一个焦点,因此基于此,注释应该简短并详细说明提交的重点。
我很喜欢在评论中发布内容,以及为什么以及如何在其他地方详细说明(最好是在您的错误跟踪中)。为什么应该是机票,并在关闭机票时,你应该有一些关于如何解决这个特定问题的说明。
如果不以其他方式处理(例如TRAC / SVN交互),则对您的错误跟踪系统的引用是好的。这样做的原因是,如果他们正在寻找有关提交的更多信息,则指向其他开发人员正确的方向。
除非需要修复非常复杂和详细,否则不要包含特定的文件名。即便如此,复杂的细节可能属于您的实施说明的错误跟踪,而不是版本控制。编辑的文件,差异细节等应该包含在版本控制中,我们不想花时间复制它。
Given these ideas, an example commit comment for me would be something like
鉴于这些想法,我的一个示例提交评论将是类似的
Req3845: Updated validation to use the new RegEx validation developed in Req3831.
Req3845:更新了验证,以使用Req3831中开发的新RegEx验证。
Short, communicates what was changed, and provides some kind of reference for others to get more info without hunting you down.
简而言之,传达改变的内容,并为其他人提供某种参考,以获取更多信息而不会让你失望。
#2
I prefix each paragraph with + - * or !
我在每个段落前加上+ - *或!
+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix
I don't think you should commit detailed description about what parts of the code are changed, because that's why every VC has diff :)
我不认为你应该提交有关代码的哪些部分被更改的详细描述,因为这就是为什么每个VC都有差异:)
#3
If you use a bug tracking system, include relevant ticket numbers.
如果您使用错误跟踪系统,请包含相关的票号。
You do not need to mention changed files, or your name. The source repository can figure that out by itself. Describing the changes also only makes sense if it is not non-trivially obvious from the diff.
您无需提及已更改的文件或您的姓名。源存储库可以自己解决这个问题。描述这些变化也只有在差异不明显的情况下才有意义。
Make sure you have a good first line, because this frequently appears in the change history view, and people need to find things by this (the bug tracking ticket number should go there, for example).
确保你有一个好的第一行,因为这经常出现在更改历史记录视图中,并且人们需要通过此查找内容(例如,错误跟踪票号应该去那里)。
Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).
尝试在单个变更集中提交相关更改(并将不相关的更改拆分为两个提交,即使是同一个文件)。
#4
I try to follow the same rule as for code comments:
我尝试遵循与代码注释相同的规则:
Explain the WHY, not the HOW.
解释为什么,而不是如何。
IMO a comment should contain a reference to the issue (task tracker, or requirement). Which files are affected is already available from the version control system. Apart from that, it should be as short as possible, but still readable.
IMO评论应包含对问题的引用(任务跟踪器或要求)。版本控制系统已提供受影响的文件。除此之外,它应该尽可能短,但仍然可读。
#5
I try to keep my fixes in separate check-ins.
我尝试将我的修复程序保存在单独的签入中。
I don't use an actual template, but a mental one, and it's like this.
我不使用实际模板,而是使用心理模板,就像这样。
Issue - dev level summary of issue.
问题 - 开发级别的问题摘要。
The issue tracker has all the management details, and the changes/diffs can be reviewed for code changes, so the comment is for dev's to understand the why/what of the issue.
问题跟踪器具有所有管理详细信息,并且可以检查更改/差异以进行代码更改,因此注释可供开发人员了解问题的原因/内容。
#6
Here's what I've seen used successfully:
这是我见过的成功用法:
- Reference to bug number or feature ID
- Brief description of the change. What was changed.
- Code reviewer (to ensure you have one) unless handled by the checkin system.
- Name of tester or description of which tests were run (if late in the process and you are being extra careful)
引用错误号或功能ID
变化的简要说明。改变了什么。
除非由签入系统处理,否则代码审查员(确保您拥有)。
测试人员的名称或运行测试的描述(如果在过程的后期,你要特别小心)
#7
I use the simple technique described by Chaosben on the JEDI Windows API blog.
我在JEDI Windows API博客上使用Chaosben描述的简单技术。
In order to get a fast view on the changes made to a repository, we suggest to write brief concise comments starting each line with one of these chars:
为了快速查看对存储库所做的更改,我们建议使用以下其中一个字符开始每行写简短的简明注释:
- + if you added a feature/function/…
+如果你添加了一个功能/功能/ ...
- - if you removed a feature/function/bug/…
- 如果你删除了一个功能/功能/ bug / ...
- # if you changed something
#如果你改变了什么
Doing it this way, other developers may find the desired revision much better.
这样做,其他开发人员可以更好地找到所需的修订版。
#8
First, commits should solve one single problem (separate commits for logically separate changes). If you don't know what to write in the commit message, or the comit message is too long it might mean that you have multiple independent changes in your commit, and you should split it into smaller items.
首先,提交应该解决一个单独的问题(单独提交逻辑上单独的更改)。如果您不知道在提交消息中写什么,或者comit消息太长,则可能意味着您在提交中有多个独立更改,并且您应该将其拆分为更小的项。
I think that commit message conventions expected and used by git makes much sense:
我认为git期望和使用的提交消息约定很有意义:
- The first line of commit message should be a short description
- If appropriate, prefix mentioned above summary line with subsystem prefix, e.g. "docs:" or "contrib:"
- In next paragraph or paragraphs describe the change, explaining why's and how's
提交消息的第一行应该是简短描述
如果合适,前面提到的前缀与子系统前缀,例如, “docs:”或“contrib:”
在下一段或段落中描述变化,解释原因和方法
#9
Keep in mind that if someone needs details of what changed, they can get a diff. That said, I just usually write a sentence or two for each major change, and then lump any minor fixes at the end.
请记住,如果有人需要更改内容的详细信息,他们可以获得差异。也就是说,我通常只是为每个重大变化写一两句话,然后在最后将任何小修正结果。
#10
There is no hard and fast rule as its plain english. I try to explain the work done in minimum words possible. Anybody looking for history of changes just want to know what happened in a particular change. If anybody is after more details then its there in the code.
它的简单英语没有硬性规定。我试着用最少的话来解释所做的工作。任何寻找变化历史的人都只想知道特定变化中发生了什么。如果有人在追踪更多细节,那么它就在代码中。
Second thing I follow is if there is any bug associated then stick that in or if its related to any dev task then associate that with the change.
我遵循的第二件事是,如果有任何相关的错误,那么坚持或如果它与任何开发任务相关,然后将其与更改相关联。
#11
If two files were changed for different reasons, they should be in different commits The only time you should commit more than one code file at a time is because they all belong to the same fix/change
如果由于不同的原因更改了两个文件,它们应该在不同的提交中每次只提交多个代码文件是因为它们都属于同一个修复/更改