程序员的那些事
2019-12-20 21:07:28 发布
【Rob Pike 教你怎么写 commit 信息】
Rob Pike 是 Go 语言核心缔造者之一。
-------
An edited version of a rant I posted internally at Google. It applies here too:
Most changelist (CL) descriptions I read are inadequate. The classic case is "Fix bug" (What bug? What fix?) but too many CL descriptions are no better.
There are many forms of "Fix bug": "Fix build." "Add patch." etc.
Here are a few I've seen lately, sanitized to protect the innocent.
"Move code from A to B".
"Phase 1."
"Add convenience functions."
and so on. None of these is helpful in any way. Although their authors may believe they are providing useful information, they are not serving the purpose of the description.
Every CL description should serve as a public record, a summary of what and why and perhaps offer advice to the reviewer. If relevant, it should provide background information such as bug numbers, benchmark results, and links to design documents. If the edits are purely automatic, say so. If the change is purely automatic except for one file, say so. In fact, say everything useful that is important, independent of the code. Do not expect the person reading the CL description to have the code handy, because in the future they might be trying to understand the history and will not have every delta visible on screen.
Even small CLs deserve a little attention to detail. Put the CL in context.
It's likely that a day or month or a year from now someone will search the history log for the change but not be able to find it because all the important information is in the code but not identified in the CL description.
In short, write the CL description for someone in the future who might be looking for your change because of a faint memory of its relevance but without the specifics handy.
I just looked around and found this one by Austin Clements, which is very good because it satisfies these criteria: What, why, and background.
----
网页链接
2019-12-20 21:07:28 发布
【Rob Pike 教你怎么写 commit 信息】
Rob Pike 是 Go 语言核心缔造者之一。
-------
An edited version of a rant I posted internally at Google. It applies here too:
Most changelist (CL) descriptions I read are inadequate. The classic case is "Fix bug" (What bug? What fix?) but too many CL descriptions are no better.
There are many forms of "Fix bug": "Fix build." "Add patch." etc.
Here are a few I've seen lately, sanitized to protect the innocent.
"Move code from A to B".
"Phase 1."
"Add convenience functions."
and so on. None of these is helpful in any way. Although their authors may believe they are providing useful information, they are not serving the purpose of the description.
Every CL description should serve as a public record, a summary of what and why and perhaps offer advice to the reviewer. If relevant, it should provide background information such as bug numbers, benchmark results, and links to design documents. If the edits are purely automatic, say so. If the change is purely automatic except for one file, say so. In fact, say everything useful that is important, independent of the code. Do not expect the person reading the CL description to have the code handy, because in the future they might be trying to understand the history and will not have every delta visible on screen.
Even small CLs deserve a little attention to detail. Put the CL in context.
It's likely that a day or month or a year from now someone will search the history log for the change but not be able to find it because all the important information is in the code but not identified in the CL description.
In short, write the CL description for someone in the future who might be looking for your change because of a faint memory of its relevance but without the specifics handy.
I just looked around and found this one by Austin Clements, which is very good because it satisfies these criteria: What, why, and background.
----
网页链接