体面编码之代码提交


每次提交的是一个合乎逻辑的工作成功。将每个功能,错误和重构与其他功能分开。这使得历史更加有用,并鼓励采用有组织的方式开展工作。如果您需要在处理功能时修复错误,请考虑使用源代码控制功能(如Git的存储库)临时删除功能更改。

更喜欢更小,更常规的提交。过大的提交更难理解和有效审查。当您达到小的里程碑时,递增地承担更大的工作量。

尽可能分离重构。重构往往更难(并且效率更低),通常包括现有代码的许多移动和编辑。将其与提交中的功能/错误工作混合使得它更难。当一个任务以一些前期非平凡的重构开始时,考虑先制作一个单独的早期pull请求,以便更早地获得对主分支的更改。这有助于避免与其他贡献者正在进行的工作发生冲突。

删除您的更改未使用的现有代码。立即删除的代码可能是代码其他部分的唯一用户。现在未使用的代码可以位于同一个文件中,代码库中的其他位置,也可以位于从UI到数据库的堆栈中。

处理或删除相关的现有和新TODO评论。现有的可以参考现在完成的工作。新的可能是临时的并且需要删除,或者参考问题跟踪器票以便以后的工作。

避免包括无关和无法解释的变化。第一项的扩展。此类更改通常是格式化问题,或在解决合并/ rebase冲突时出错。

避免包括遗留未使用的代码。这样的代码通常来自实验,尝试不同的方法或反复试验。它可能没有效果,甚至根本没有运行。CSS特别容易受此影响。

避免意外包含不需要的文件,如个人配置和日志文件。使用源代码管理工具的忽略文件功能可防止意外包含此类文件。签入忽略文件。但是,应该检查整个团队需要保持一致的配置。

提交消息注释
总结前70个字符的变化。这使得在阅读日志时可以一目了然。默认情况下,许多源控制工具会隐藏其余的消息。

包括“为什么”以及“什么”。简要解释一下正在做什么。这是在提交的上下文中 - 它需要比一个大功能的标题名称更精细。请记住,差异的细节可以在差异中找到。然而,“为什么”并不总是显而易见或立即明确,因此请将其包含在消息中。对于更复杂的更改或重构,对“什么”的简要描述可能会有所帮助。

根据项目约定引用相关问题跟踪器ID。这些标识符允许方便地找到关于变更的进一步信息。最常见的是,它适用于目前正在处理的问题,但也可能是其他有用且相关的问题。前一种情况可以使用源控制分支检测提交消息钩子(例如这一个)自动化。

有关优秀提交消息为何如此重要的更多信息,我建议介绍部分,特别是Chris Beams 撰写的“如何撰写Git提交消息”一文。

提交
保留行历史记录。源代码控制工具可以显示每行所做的最后一次更改的逐行视图(通常称为“注释”或“责备”)。提交更改然后再提交将代码更改回原来的方式,使得此功能不那么有用。编辑此类提交,或组合(“挤压”)有大量流失的提交组,可以在这种情况下提供帮助。

看看承诺了什么。添加工作文件夹中存在的所有更改非常容易,可以快速提交。然而,单独添加每个文件,快速查看每个文件以及每个文件的更改,让您有机会发现任何不对劲的事情。

拉请求
拉取请求和代码审查流程高度针对个别团队的情况和偏好。这里的要点不可避免地反映了我的经历,但其中许多应该是一般的/适应性足以与其他团队相关。做适合您的团队的工作,以便从作者和评论者花费的时间中获得最大的收益。

要阅读有关拉取请求和代码审查的更多信息 - 包括文化,行为,实践和工具 - 请从代码审查真棒列表开始

一般(拉动请求)
争取小拉请求。大量拉动请求更难以审查,导致较差的反馈,未被注意的问题,“速度审查”,以及进展批准的进展缓慢。如果您无法拆分大型功能的工作项(由于流程或政治原因),请考虑将一系列较小(例如200-400行)拉取请求的增量技术引入“收集器分支”,最终形成一个大的从该分支向主/主干拉请求。

争取短暂的拉动请求。任何正在进行或正在审查的分支机构工作尚未成为其他人基于其工作的主/主干的一部分。这可能导致冲突,这些冲突既费时又容易解决。长时间打开会增加拉请求在更长时间内打开的可能性 - 因为它需要在其他拉取请求合并之前进行更新(可能涉及冲突解决)。考虑设置一些通用和“SLA类型”基本规则来促进短期PR,例如:在提交后的n小时内进行审核,并在开始新工作之前审核PR或解决反馈。提出小拉请求有助于保持短暂的生命。

自动化繁琐的事情。配置构建以要求传递代码样式和静态分析检查。通过工具比人们更快,更便宜,更一致地检测到这些问题。

预先设定期望。使贡献者可以轻松提交将首次批准的拉取请求,或者至少不需要进行重大更改。有助于此的事情包括明确的要求,对应用程序架构和编程模式/实践的共同理解,以及在实现开始之前共享设计思想。

在提交之前
构建成功。这包括运行测试和自动代码质量检查。

分支是最新的目标分支。这是确保要合并的更改与最新版本的目标分支兼容并集成的唯一方法。这是通过将目标分支合并到源分支(或在目标上重新定位源)来完成的。

自我审查代码。阅读要求,并查看您自己的代码。这是一个发现错过的任何问题或事情并立即修复的机会 - 增加首次批准的可能性。

完成预提交清单。清单可以帮助每个人记住需要完成的事情。提交前检查清单需要的是取决于团队和项目,并且应该随着时间的推移而发展 - 例如,什么事情总是作为反馈出现。为了避免稀释其重要性,它不应该太长或包括琐碎的事情。如果存储库支持拉取请求描述的模板,请创建一个包含核对表的模板 - 否则,快速填充拉取请求描述字段的书签可以提供帮助。

更新问题跟踪器票证(如果适用)。如果通过其他渠道(电子邮件,即时通讯,面对面)对要求进行了澄清,更正或修改,请记录这些内容。这有助于确保每个人(审阅者,测试人员,产品所有者)使用正确的信息,因为功能/修复程序正在发布。

为测试人员添加“内部见解/建议”。根据您实施/修复需求/错误的经验,这是您认为可以帮助他们的任何有用信息 - 在不审查代码更改的情况下无法知道的事情。将其添加到问题跟踪器票证。示例包括:难以实现的事物,受影响的看似无关的区域/功能(例如,如果修改了公共组件),以及重构更改或技术任务的范围。

提交
提供信息标题。能够快速识别存储库中打开的许多拉取请求是有帮助的。仅将问题跟踪器ID用作标题时,这是不可能的。

提供信息以帮助审核人员尝试更改。示例包括合适的测试数据的位置,所需的特定用户类型/配置以及服务端点详细信息。将相关部分添加到问题跟踪器故障单中。

添加带有省时提示的注释。作为评论者考虑,并添加评论,这将有助于他们充分利用他们的时间。例如,指出简单移动的代码,解释一个嘈杂的差异区域,其中几乎没有实际的变化,或解释一个可能提示解释请求的区域。

请注意需要注意的代码区域。避免依赖评论者接受事物(或希望他们不接受)。完成这项工作后,您可能会比审稿人更深入地了解它。评论那些感觉不太合适的事情(新的或现有的),您不确定的事项(要求或技术),或您所做出的利益决定。

审查并提供反馈
检查整个变化。代码库中的所有内容都直接或间接地为应用程序的功能和质量做出贡献。避免考虑某些不值得审查的区域,并跳过它们 - 例如测试,构建配置或样式表。

运行代码。仅仅因为它看起来不错,并不意味着它做对了。如果项目工具使人们难以在他们自己的工作和运行审查分支之间切换,那么解决这个问题。

注意......一切,真的。利用您的经验,知识,指南和其他任何东西。它是做正确的事情,它是否有意义,它是好的,它是可维护的,是否经过测试,假设/解释是否清晰有效等等。

问问题。代码审查有助于在团队中分享代码库的知识,并帮助贡献者相互学习。如果某些事情不清楚或不明白,请询问。如果整个变更难以审查并且难以掌握,则可能需要改进。

做出明确的评论,解释不明显的推理。直接的好处包括避免澄清请求(延迟进度),以及避免因错误解释的注释而进行的意外修订。长期利益是作为作者和评论者的其他参与者的升级。这有助于提高整体质量,因为单个人审查所有更改通常是不切实际的。

寻找拼图的缺失部分。当前代码,加上正在审查的更改,以及其他积压工作项目 - 将在某个时候构成软件的可释放版本。指出您认为缺少但需要的任何内容 - 可能需要为其创建积压工作项。

解决反馈问题
解决注释适用的所有实例。审稿人可能没有注意到评论适用的所有地方,或者没有对所有评论都进行评论以避免引起噪音(这是一种很好的做法)。考虑评论所作的观点是否适用于其制作的特定行以外的其他地方。

使审阅者可以轻松查看修订版。根据使用的存储库/工具,编辑现有提交可能会使查看更改的内容变得困难。针对个别评论(或其逻辑组)的细粒度提交便于查看并与原始评论相关联 - 允许审阅者查看响应他们的反馈所做的更改。它们还可以创建更好的版本控制历史 按照“地址pr评论”的标题进行的单一广泛提交没有任何这些好处。

尽量减少反复来回。通过对话更容易解决一些问题,而不是重复更改和评论循环,或长时间运行的评论线程讨论。当您发现其中一个来回/流失情况时,请进行对话或建议短对编程会话。

在合并之前
构建成功。在允许合并之前,配置工具(存储库和CI服务器)以要求成功构建最新版本的分支。

分支是最新的目标分支。在允许合并之前,将存储库配置为要求源分支不在目标之后。

所有评论都已得到解决。这通常意味着进行修改,回答评论者的问题(令他们满意),或结束讨论。跟踪未完成的评论可能很困难 - 诸如反应(竖起大拇指等)或任务复选框等存储库功能可以提供帮助。配置存储库(如果支持)要求在允许合并之前完成所有任务。

检查所有核对表项目。拉取请求核对表除了预先提交的项目之外还可以包括合并前项目。

审查人已经给予了充分的批准。什么是足够的取决于团队和项目。通常需要最低数量的批准。可能有必要进一步要求一组被认为负责任的人批准一个/几个。在允许合并之前,配置存储库(支持的任何程度)以要求这些批准。此外,使用良好的判断来决定是否应该从区域/域/技术专家等特定人员那里寻求批准。

如果批准后更改,批准仍然有效。在另一位审稿人批准后,一位审稿人提供的反馈有时会产生重大修改。在这种情况下,已经批准的审稿人可能希望重新审核。可以将存储库配置为在进行后续更改时撤消批准,但由于合并或微不足道的更改会触发它,这往往会变得乏味。