Git最佳实践--如何编写有意义的提交、有效的拉动请求和代码审查

迪鲁宾
310 阅读16分钟

作为开发人员，我们定期推送代码提交--一段时间后，这几乎成为我们的第二天性。

但这是否意味着我们做的事情是正确的？熟悉往往会导致马虎和忽视基本的东西。

在这篇文章中，我们将探讨:

  • 如何编写有意义的 Git 提交信息
  • 如何创建高效的拉取请求（PR）
  • 如何在代码审查过程中获得真正的好处，以及一些需要遵循的最佳实践

前提条件。

我喜欢用VS Code作为我的代码编辑器。我也用这个作为我的Git编辑器。我发现在我写代码的时候，在同一个地方写提交信息更容易。它也给了我更多的空间来写提交信息和描述。

如果你还没有这样做，请按照以下步骤使 VS Code 成为你的默认 git 编辑器。

  1. 打开VS Code，在命令调色板中搜索:

外壳命令。在PATH中安装'code'命令

2.然后在你的终端运行以下命令:

git config --global core.editor "code --wait"

现在当你运行git commit 或git -config --global -e 时，它将在 VS Code 的文件中打开 Git 编辑器。

注意:所有给定的命令都要在终端中运行（无论是你选择的终端，还是VS Code中的集成终端）。

如何编写有意义的提交信息

在提交代码时，写一些有用的提交信息是很有帮助的。这里有一些提示和最佳实践，可以帮助你做到这一点。

使用指令性命令

在提交信息前加上命令式命令，例如。fix,refactor,add, 和remove

这是因为你应该能够在提交信息中加入以下短语的后缀

"如果应用，这段代码将..."

并告知其他开发者它将做什么，例如。

如果应用，这段代码将修复登录按钮不显示的问题

保持简短

你不是在写独白，所以要简短。一般来说，一条提交信息不应超过50个字符。

设身处地为开发者或评审员着想。试着想一想，如果你在看这个 repo 的 Git 记录，你会想知道什么。

  • 你完成了什么工作？
  • 你为什么要这么做？
  • 它对代码库有什么影响？

下面是一个简明扼要但内容丰富的提交消息的例子:

fix issue with login button not showing

如何使提交信息简短而有帮助

在你的提交中，你可以包含一个提交描述，让我们对你所做的事情添加更多细节/背景。

在提交信息下面加一个空行，然后在第三行开始写描述。它看起来像这样:

fix issue with login buttton not showing

- update login form validation
- update login styling for showing the button

现在，当其他开发人员在审查Git日志、提交或需要恢复代码时，他们可以更好地了解会发生什么效果，以及是否会导致任何破坏性的变化:

image-29

无益的提交信息的例子

另一方面，这里有一些无效的提交信息的例子:

  • fixed bug - 没有提到具体修复了什么bug，所以对git历史/日志没有任何价值。这将使回顾以前的提交变得非常困难，而且很费力。作为一个开发者，你必须打开每个这样的提交来了解它到底在做什么。
  • refactored due to PR comments - 这条消息没有给我们任何关于修改内容的信息。我们不得不去寻找拉动请求，以收集关于所做修改的任何背景，或者再次打开提交。
  • fixing previous commit - 又是缺乏上下文
  • made tests pass - 哪个测试文件被更新了？你至少应该给出被修复的测试文件的名称或区域。

所有这些都是提交信息的糟糕例子，因为它们含糊不清，缺乏信息，也缺乏上下文。它们迫使团队成员做更多的工作，以便了解发生了什么，这在任何团队中都是不可接受的。

如何制定一个提交策略

你可能认为提交代码就像直接提交和推送代码一样简单。但是，这里面还有一些内容。

让我们来谈谈如何制定一个有用的提交策略，以保持一致性并做出有用的提交。

做出小而具体的提交

较小的提交可以让你在出现问题时更容易将代码恢复到之前的状态。如果你的提交影响了太多的领域，恢复可能意味着失去大量的代码。

如果代码只与一个目的相关，评审员也更容易理解代码在做什么。

让我们看一个现实生活中的例子，这将如何工作。首先，我们需要添加我们的相关文件的变化。我们可以通过运行以下命令来查看我们的分支中哪些文件被修改了git status

Screenshot-2022-08-01-at-23.28.59

git status的输出示例

正如你所看到的，有各种文件已经被修改/添加到项目中。不过，它们都是针对项目的不同区域。遵循 "保持提交量小且有关联 "的黄金法则，让我们看看如何将其付诸实践。

使用git add 后面的文件名，我们可以只提交相关的文件。我们通过使用git add 命令，加上我们想添加的文件名，像这样一个接一个的添加。

git add login.test.ts login.ts

如果我们现在检查git status ，我们会看到两个暂存的文件:

Screenshot-2022-08-01-at-23.34.35

文件暂存后的 Git 状态输出示例

我们有了这些文件，现在要创建我们的提交。像往常一样，我们将利用git commit ，它将在VS Code中打开git编辑器（因为我们之前是这样设置的）。如果你跳过这一步，提交将在你喜欢的编辑器中打开。

我们将添加一个修改的提交信息:

Fix issue with login buttton not showing

就这样，一个小小的相关文件提交。提交信息告诉我们到底做了什么，问题在哪里，以及问题的一些小背景。

提交的坏例子

既然我们已经做得很成功了，让我们来看看一个坏的例子。

想象一下，我们已经完成了所有这些工作，而开发者使用git add -A 命令将所有更改/添加的文件一次性归档:

Screenshot-2022-08-01-at-23.45.26

多个不相关的文件被暂存提交的例子

现在他们利用单行的 Git 命令创建了一个提交信息:

git commit -m 'Updated various areas such as validation, registration and products pages'

为什么会这样呢？

  1. 首先，这个提交中发生了太多的事情。太多的文件意味着，如果我们需要恢复验证的变化，只是我们无法做到。我们必须恢复整个提交，否则就会失去产品和注册的变化。
  2. 提交信息很冗长。我们可以去掉一些不必要的词，比如 "各个领域，如"。 它没有给提交信息带来任何价值，而且占用了可以用来表达更多内容的字符。
  3. 我们没有使用前面提到的命令式语气。我们应该把 "Update "改为 "Update"。

如果应用，这段代码将解决提交按钮在登录时不显示的问题

中途总结

所以在这一点上，我们已经学到了:

  • 如何制定一个有用的提交信息
  • 如何制定一个有效的提交策略，使我们能够轻松地跟踪相关的修改，以及一个更可维护的代码库。
  • 什么是糟糕的提交

如何创建高效的拉动请求

决定何时推送

推送是指将你的提交提交到服务器/远程源码上，准备创建一个拉取请求（PR）。我建议在当前功能或错误完成后立即推送。

另外，保持你的 PR 小而精，只包含相关的提交，也是一个好主意。举个例子，如果你有以下的提交:

  • Add new product search component
  • Add unit tests for product search component
  • Add documentation for product search component

因为所有这些提交都与同一个组件有关，所以建议将它们拉到一个 PR 中。

而像这样的情况

  • Fix bug within login screen
  • Refactor registration page for performance
  • Update validation tests for login form
  • Update login tests for forgotten password
  • Update unit tests for product search component

不应该放在同一个 PR 中，因为发生的事情太多了。这些提交应该被归入当时包含相关提交的几个PR。

如果这是一个分支的 Git 日志，由于提交的顺序问题，你将无法创建一个只有相关文件的拉动请求，因为你不能简单地告诉 Git 你想把提交 1、3 和 4 放到这个 PR 中。

保持小规模

记住--就像你的提交一样，保持你的 PR 的规模。没有人愿意在50多个文件的拉动请求中涉险。这样做的结果是，你的审查会受到 "对我来说很好 "的困扰。

当你创建一个大的PR时，它被翻译成*"我* 懒得看所有这些文件，但略微看了一下，看起来还不错"。另一方面，对于一个较小的PR，它的意思正是它所说的。

有时，大的拉动请求是不可避免的，比如在更新基础函数和类似的时候。但是，你应该尽量注意如何限制对其他开发者的影响。

如何让你的分支准备好接受代码审查

创建Pull Request的具体过程会因你所使用的版本控制托管平台而不同，但概念是相同的。

首先，你应该从你的 repo 中检查出main 分支。然后运行git pull ，这将把main 的所有最新代码放到你的本地开发系统中。

一旦你完成了这项工作，你就可以使用git checkout 和你的分支名称，例如git checkout login-fixes ，回到你自己的分支。

现在我们需要把main 分支的代码放到我们的分支中。我们可以利用git merge 命令来做这件事:

git merge main

如果有变化，也就是说，从主干线拉过来的文件有变化，你就需要创建一个 "合并提交"。这只是对你自己的分支的另一个提交，包含了合并后的变化。

只需创建另一个提交，并说明你已经从主干线合并了，就像这样。

git commit -m 'Merge main into login-fixes'

将你的修改推送到远程服务器上，使用git

如何创建拉取请求

最简单的方法是通过你喜欢的版本控制平台的网页界面来完成。在这个例子中，我们将使用GitHub。

只需导航到你的 repo，然后点击 Pull Requests 标签:

image-21

拉动请求标签 - GitHub

选择 "新的拉动请求"

image-22

新的拉动请求 - Github

image-24

当你创建一个拉动请求时，使用一个描述PR的标题，就像你在提交时那样:

PR - Fix login button not showing.

它可以为审查者提供一些背景信息，说明为什么这个PR是必要的，或者PR描述中的任何额外信息。

正如你在上面看到的，我选择了包括修复的内容，可能会使审查更顺利。我还包括了一些重要的信息，即在另一个PR被合并之前，这个PR不应该被合并。

当为一些公司工作时，他们可能会要求你在PR标题中加入一个票据参考，但我已经讨论过为什么我认为不需要这样做。

PR标签

如果你想让它更清晰，你可以利用PR标签。这些标签可以应用于PR，以说明PR的状态，或向其他人提供简单的信息。你可以在拉动请求页面的右边找到它们:

image-26

你可以从预定义的标签中选择，或者添加你自己的标签:

  • 点击标签
  • 输入你希望使用的标签。在我们的方案中，我们要添加一个叫做Do Not Merge 的标签。
  • 输入数值后按回车键，你可以配置标签的颜色和名称。保存后，你现在可以再次输入它，它将显示在列表中。
  • 选择你的新标签，然后就可以了。

image-27

点击创建拉动请求

image-28

就这样，你已经创建了你的第一个拉动请求。

如何审查一个PR - 最佳实践

审查PR时应注意的事项

总是退一步想一想一个好的代码审查的关键因素。以下是一些需要考虑的要点:

  • 代码是否遵循你的团队的编码准则？
  • 代码是否符合其目标/验收标准？
  • 代码是否清晰易读，是否很容易理解它在做什么，而不需要大量的注释/文档？(这一点对我来说是最重要的，因为我是一个描述性函数和变量名称的超级粉丝）。
  • 考虑到安全、性能或简单的易读性，代码是否需要任何重构？
  • 代码是否遵循简单的设计模式/原则，如单一责任、抽象、封装等等？如果没有，你可以就如何实现这一目标提出建议，或者告诉那些不熟悉的人这意味着什么，以及它的好处。
  • 是否有任何 "神奇的数字/字符串 "可以更好地作为一个常量或命名的变量？

及时审查PR

虽然你不一定觉得有义务立即查看一个PR，但也不要让作者悬空。这个PR可能会阻碍未来的工作，或者它可能很重要（如果是这样，作者应该明确说明）。

尽量保持讨论和公关意见的畅通。如果这样做更容易，你可以跳上电话（如果是远程）或在办公室拉上椅子，一起讨论公关。这可能会加快进程，并减少来回的等待。

综上所述，不要急于进行代码审查。要一丝不苟，仔细阅读每个文件和改动。我建议你把修改的分支拉下来，让自己看一下整个项目，而不仅仅是修改的那几行。

很多时候，如果你只看一两行代码的修改，你就不会知道代码到底应该怎么做。但如果你看的是整个文件，你就可以遵循流程。

如果你使用VS Code和GitHub，你可以利用他们自己的扩展来查看拉动请求和查看评论，同时在VS Code本身中查看PR分支。

我们都是人

请记住，我们都是人，人们在编码时经常会犯错误，可能会忽略一些事情。

不是每个人的编码方式都和你一样，所以不要因为他们的方式和你的方式不同就简单地要求修改。这并不意味着他们做错了，也不意味着你的方法是最好的。

清楚地描述修改，谨慎地表达你的意见

拉取请求不是考试，也不是让你严厉批评别人工作的机会。它是一个学习的机会，也是一个确保最好的代码进入主分支的机会。这是关于代码质量和代码是否符合验收标准的问题。

想想你在提出建议时使用的语言。PR评论与git提交信息是相反的。我们不再使用命令式的语气。不要命令他们进行修改，而是用从句的语气来提出柔和的建议。

当你在批评一个人很可能投入了大量精力的工作时，使用这样的句子。

如果是我，我会把这个if语句改成switch case语句，因为这样更容易阅读。

或者

也许可以考虑把这个变量重新命名为一个更直观的名字，比如{替代}，以便从最初的阅读中更容易理解它在做什么。

如上所述，试着加入你的理由，说明你为什么要提出这个修改请求。这将使请求更有影响力，并允许作者思考是否最好进行修改，或者也许引发讨论以达成妥协。

提供改进建议

大多数Git系统都允许你点击你希望修改的那一行，然后添加注释，这样就可以更简单地指定你希望修改的确切代码行。

像GitHub这样的主机供应商有一个 "建议 "功能，允许你在注释中直接添加代码建议，这些建议可以立即被接受并在PR中提交。

如果没有这个功能，一定要确保你所要求的东西是清楚和简洁的。甚至可以改写，或者在评论中写出你的建议，比如。

也许可以考虑把这个if/else语句改成一个三元语句，就像这样。

var backgroundColor = isError ? 'red' : 'blue'

这使建议变得清晰，甚至加快了重写的过程（使用复制和粘贴）。

不要害怕为你的代码辩护

记住PR是一种讨论。这是一个双向的过程，让你有机会为你的代码辩护，并以更多的背景解释你的想法。

仅仅因为代码可能看起来不完美，可能有一个原因。可能有一些你无法控制的事情，迫使你不得不以某种方式来写代码。

不要害怕提出反驳，但是要准备好有效的理由，如果你真的相信你的解决方案。

告知PR已被批准

现在很多人都会把GitHub或版本控制的邮件通知过滤到一个文件夹里，由于仓库、提交、分支等的更新量很大，这个文件夹很少被查看。

为了加快这个过程，让作者更有乐趣，只需给他们发个消息。现在许多公司都提供某种形式的即时通讯服务，为什么不使用它呢？

在你的即时通讯平台上为公关设置一个特定的频道。在频道/聊天室中发布你的公关链接，并允许评论员通过在主题中回复来更新他们的进展。添加一个表情符号，使其更加轻松（因为我们都知道公关可能很无聊，所以为什么不把它们弄得更生动一点）。

总结

在这篇文章中，我们已经学会了:

  • 如何设置VS Code与Git的集成
  • 如何编写有用的 Git 提交信息
  • 何时提交才能让团队更轻松
  • 如何有效地对PR进行代码审查
  • 如何以帮助所有团队的方式来处理PR。

希望你能学到一些新东西，感谢你阅读我的文章

avatar
文章
阅读
粉丝