代码健康(4):使用较长的命名,也可能降低可读性

乔梁 | 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 单是相辅相成的, 它们从不同的角度提供了上下文。

请记住,这样的上下文甚至对你自己也非常有用。它能很容易地提醒你,上周做了什么,甚至是去年做了什么。未来的某一天,你一定会感谢今天写下清晰上下文的你!