| 2021-03-04
利用“ commit message ”和“ issue ”提供上下文
阅读其他工程师的代码有时会感觉像是在考古，其中可能充满了难以破译的，奇怪（甚至令人瞠目结舌）的描述。**写代码一定是有其意图的。然而，有些时候，我们写的代码本身却没能清楚地表达它的意图。**所以，在这种情况下，你可以通过编写类似“为什么要修改这段代码”这样的上下文来解决这种知识鸿沟。而代码注释就是做这个事情的。然而，有时候仅仅使用注释也无法提供足够多的信息。
其实，还有两种方式来表明上下文：
提交注释信息（ commit message ）
提交注释信息是提供上下文的最简单，最易找到的方法之一。当有些代码的意图表达得不是很清楚时，可以看一下提交注释信息，它可能对代码做了很好的解释，可以深入了解代码的用途。
提交注释信息的第一行应该独立成行，因为像 GitHub 这样的工具会在提交列表页面中显示第一行。 独立第一行让你更快地浏览代码历史记录，快速建立对源文件随时间演变的理解。例如下面这一行：
This allows consumers to easily discover the new Frobber widget and add it to their application.
更多关于提交注释格式的实践，请参见 请参见《如何写好提交注释？》
Issue 单
你可以用一个 issue 单来跟踪一个缺陷或特性，或者某次重构的完整历史，这个 issue 单包括原始问题的描述，团队内的设计讨论，以及用来解决该问题的注解。这让你很容易在一个地方就看到所有相关的提交，让其他人容易跟踪某个具体问题的状态。
大多数提交应该与某个 issue 单相关联。但是，并不需要为某个临时性且相对独立的提交都创建一个对应的issue 单(例如一次性的清除或格式化代码，或者不在计划之内的微小变更)，因为在 commit message 或源代码中通常包含它们所有的上下文。
信息丰富的 commit message 和 issue 单是相辅相成的， 它们从不同的角度提供了上下文。
请记住，这样的上下文甚至对你自己也非常有用。它能很容易地提醒你，上周做了什么，甚至是去年做了什么。未来的某一天，你一定会感谢今天写下清晰上下文的你!
发表时间：September 11, 2017
原文作者：Chris Lewis
原文链接：Code Health: Providing Context with Commit Messages and Bug Reports