SVN/版本化文件提交注释应包含哪些信息？
我很好奇版本化文件提交注释中应该包含什么样的内容。它应该概括地描述发生了什么变化（例如“小部件屏幕已更改为仅显示活动小部件”）还是应该更具体（例如“在 fetchWidget 查询的 where 子句中添加了一个新条件，以默认情况下仅检索活动小部件” ")
一次提交应该有多原子？只是在一次提交中包含更新的查询的文件（例如“更新小部件屏幕以默认仅显示活动小部件”），或者应该与其他几个更改+屏幕的界面更改共享相同的提交并提供更一般的描述就像（“更新了小部件屏幕：A）默认情况下仅显示活动小部件B）添加了用于切换显示非活动小部件的按钮”）
我看到颠覆提交评论的使用方式非常不同，并且想知道其他人在哪些方面取得了成功。有些注释就像“更新的文件”一样简短，而另一些注释则有很多段落长，还有一些注释的格式可以查询并与某些外部系统（例如 JIRA）关联。
我非常详细地描述了更改的原因以及具体的技术更改。最近，我一直在缩减规模，只是给出一般性的“这就是我在此页面上更改的内容”之类的评论。
I'm curious what kind of content should be in a versioned file commit comment. Should it describe generally what changed (e.g. "The widget screen was changed to display only active widgets") or should it be more specific (e.g. "A new condition was added to the where clause of the fetchWidget query to retrieve only active widgets by default")
How atomic should a single commit be? Just the file containing the updated query in a single commit (e.g. "Updated the widget screen to display only active widgets by default"), or should that and several other changes + interface changes to a screen share the same commit with a more general description like ("Updated the widget screen: A) display only active widgets by default B) added button to toggle showing inactive widgets")
I see subversion commit comments being used very differently and was wondering what others have had success with. Some comments are as brief as "updated files", while others are many paragraphs long, and others are formatted in a way that they can be queried and associated with some external system such as JIRA.
I used to be extremely descriptive of the reason for the change as well as the specific technical changes. Lately I've been scaling back and just giving a general "This is what I changed on this page" kind of comment.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（8）
一些指导原则：
Some guidelines:
它应该简要解释提交包含的内容。这应该包括错误修复或增强的票号。我听过的关于编写注释的最佳建议是“编写代码时，就好像下一个维护您代码的人是一个知道您住在哪里的杀人狂”。这同样适合提交注释。
it should briefly explain what the commit contains. This should include a ticket number for a bug fix or enhancement. The best advice I have ever heard about writing comments is this "Code as if the next guy to maintain your code is a homicidal maniac who knows where you live" This is equally appropriate to commit comments.
有用的提交注释是那些添加了不易从更改本身中提取的有用信息的注释。查看差异将显示更改的内容，因此提交注释应集中于解释为什么进行更改：
修复了由于 NULL 指针取消引用而导致的崩溃（错误 ID 234）。
添加了与服务器断开连接的命令（功能请求 22）。
清理了代码以供将来更改。
另一种有用的注释是总结一组较大更改的总体目的的注释：
Useful commit comments are those that add useful information that isn't easily extracted from the changes themselves. Looking at the diffs will show what changed, so the commit comment should concentrate on explaining WHY the changes were made:
Fixed crash due to NULL pointer dereference (bug ID 234).
Added command to disconnect from server (feature request 22).
Cleaned up code for future changes.
Another useful sort of comment is one that summarizes the overall purpose of a larger set of changes:
就我个人而言，我尝试对我更改和/或添加的内容进行简要总结。这会提醒我，“哦，是的，这[可能]是我向业务对象添加额外规则的地方。”因为我总是可以运行“diff”来查看具体发生了什么变化。
Personally, I try to make a brief summary of what I changed and/or added. Something that will remind me, "Oh yeah, this is [probably] where I added that extra rule to the business object." Because I can always run a "diff" to see specifically what changed.
如果您使用错误跟踪系统，最好包括您正在处理的适用于更改的错误/增强#。很多时候你只是重写错误描述中的内容。
If you use a bug tracking system it's best to include the bug / enhancement # you are working on that applies to the change. A lot of times you'll just be re-writing what's in that bug description anyway.
它应该包含更改的小摘要（以允许在更改列表中进行过滤）以及应用更改的原因。
新代码的文档属于源代码本身；不在日志消息中。 （并且仅应用于旧代码的注释应该被删除。您可以随时通过 SCC 系统的历史记录查看这些旧注释）。
It should contain a small summary of the changes (to allow filtering in a list of changes) and why the change was applied.
The documentation of the new code belongs in the source code itself; not in the log message. (And comments that only applied to the old code should be removed. You can always look at those old comments via the history of your SCC system).
当我思考该写什么/不该写什么时，对我有帮助的一件事是，最终应该可以从提交评论中编译出内部的技术发行说明。
我还发现在提交注释中建立标签非常有用，例如 #doc、#typo、#refactor，...
提交时我不会过于描述性 - 以某种方式做某事的原因应该在文档，或者在代码注释中（IMO）。
One thing that helps me when thinking about what to write/what not to write, is that eventually it should be possible to compile internal, technical release notes from the commit comments.
I also find it very useful to establish tags in the commit comments, like #doc, #typo, #refactor, ...
I wouldn't be all too descriptive when committing - the reasons for doing something one way or another should be in the documentation, or in the code comments IMO.
使用现在时将更改写成“命令”，重点关注“原因”和功能。
换行以提高可读性。
使用点来分隔相关的更改组。
也避免在标点符号后使用大写字母，以使大写字母仅与代码相关。
当出现大量新的连续“命令”时，避免使用太多“和”，而只使用逗号或 ;如果你愿意的话。
使用“次要”来描述与“清理代码”或“不感兴趣”更改相关的一组或单个更改。
或者
当“就像没有明天一样”一起提交许多功能时，您总是可以提及特定的行，我很少使用行信息。
Write as if the changes are instead "commands" using the present tense focussing on the "why" and the functionalities.
Break lines for more readability.
Use dots to separate related groups of changes.
Avoid using capital letters after punctuation as well to make capitals only code related.
Avoid using too many "and" when there is a river of new sequential "commands", instead only use commas or ; if you prefer.
Use "minor", to describe a group or a single change related to "clean up code" or "not interesting" changes.
or
When committing many functionalities all together "like there is no tomorrow", you can always mention specific lines, I used line info very rarely.