├── README.md ├── graph ├── code-review.svg ├── merge_MR.gif ├── new_MR.gif └── review_MR.gif └── review ├── CodeReview └── index.md ├── Developer └── index.md ├── Mechanism └── index.md ├── Reviewers ├── Checklist.md ├── comments.md ├── index.md └── navigate.md └── index.md /README.md: -------------------------------------------------------------------------------- 1 | # 袋鼠云数栈前端团队代码评审工程实践文档 2 | 3 | ## 代码评审指南介绍 4 | 5 | * [代码评审指南指引](review/index.md), 包含 4 个子章节： 6 | * [代码评审指南](review/CodeReview/index.md) 7 | * [代码评审者指南](review/Reviewers/index.md) 8 | * [代码开发者指南](review/Developer/index.md) 9 | * [代码评审机制保障](review/Mechanism/index.md) 10 | 11 | ## 术语 12 | 13 | 部分文档中会用到一些术语，特在此说明: 14 | 15 | * **MR**: "Merge Request."的缩写，代表正在进行代码评审的变更 16 | * **LGTM**: "Looks Good to Me."的缩写，评审者批准**MR**时会这么说 17 | * **SGTM**: “Sounds Good To Me."的缩写，评审者批准**MR**时会这么说 18 | * **WIP**: “Work In Progress.”的缩写，如果你有个改动很大的 **MR**，可以在写了一部分的情况下先提交，但是在标题里写上 WIP，以告诉项目维护者这个功能还未完成，方便维护者提前 review 部分提交的代码 19 | 20 | ## 注意事项 21 | 22 | * 经常进行代码评审 23 | * 代码评审不要太正式，要短 24 | * 尽可能让不同的人评审你的代码 25 | * 保持积极的正面态度 26 | 27 | ## 常见问题 28 | 29 | * **代码评审者提出的都是一些编码风格和代码规范的东西？** 30 | 31 | 编码规范应该交给工具去做，代码需遵循数栈代码风格指南 32 | 33 | * **为什么要鼓励为主而不是责罚并举？** 34 | 35 | 众所周知代码评审并不容易施行，因为它是团队和个人长期才能感受到好处的过程，即使不做似乎也看不到啥影响，业务也照跑，而惩罚是阶段性的反馈，所以现阶段还是以鼓励为主，但是由于对代码提交人和代码评审人要求不同，对提交人的责任要求更大点。对审核覆盖率有要求，也有责任推进评审进度。 36 | 对于代码评审主要是鼓励，因为代码评审是利他行为。在某些情况下会有一些惩罚要求：该模块很重要，引发了故障。而此问题是可以通过明显的评审发现的，此时也要承担责任 37 | 38 | * **某个需求（项目）留给开发时间非常紧张时怎么办？** 39 | 40 | 可以不进行代码评审，优先保证按时需求（项目）上线 41 | * **周末出现线上紧急 bug 要遵循代码评审流程吗？** 42 | 43 | 可以不进行代码评审，以快速修复 bug 为主，或者采取 onCall 的方式让维护者尽快评审 44 | 45 | ## 路线图 46 | 47 | * [x] [评审模版](https://github.com/DTStack/devops/blob/main/.github/merge_request_template.md) 48 | * [x] **代码评审指南 2.0**达成共识 49 | * [x] **代码评审指南 2.0**宣讲&落地 50 | * [x] 整理输出团队自身的 Checklist 51 | * [x] [代码风格指南落地](https://github.com/DTStack/Code-Style-Guide) 52 | * [x] [输出ko-lint-config & eslint-plugin-dt-react package](https://github.com/DTStack/ko/tree/master/packages/ko-lint-config) 53 | -------------------------------------------------------------------------------- /graph/code-review.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /graph/merge_MR.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/DTStack/code-review-practices/5d090f98550fbe860b30067bd2c0ba5d4b95223d/graph/merge_MR.gif -------------------------------------------------------------------------------- /graph/new_MR.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/DTStack/code-review-practices/5d090f98550fbe860b30067bd2c0ba5d4b95223d/graph/new_MR.gif -------------------------------------------------------------------------------- /graph/review_MR.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/DTStack/code-review-practices/5d090f98550fbe860b30067bd2c0ba5d4b95223d/graph/review_MR.gif -------------------------------------------------------------------------------- /review/CodeReview/index.md: -------------------------------------------------------------------------------- 1 | # 代码评审 2 | 3 | 项目的代码是托管在公司内网的 Gitlab 上的，于是开始摸索着基于 GitLab 中项目的**MR**进行他人代码评审，目前代码评审流程机制及使用体验上有一些不完善的地方 4 | 5 | - 平台无法设置 CI 不通过的情况下允许 **MR**合并 6 | - 平台评论及反馈不友好，无法直观对比不同提交版本之间的差异及针对评论的修复情况 7 | - 平台问题管理及**MR**绑定没有 Github 平台强大 8 | - 平台发起 1 个**MR**，无法指定多人参与代码评审 9 | 10 | ## 代码评审目标和原则 11 | 12 | - 提高代码质量，及早发现潜在缺陷，降低修改/弥补缺陷的成本 13 | - 促进团队内部知识共享，提高团队整体水平 14 | - 评审过程对于评审人来说，也是一种思路重构的过程，帮助更多的人理解系统 15 | - 是一个传递知识的手段，可以让其它并不熟悉代码的人知道作者的意图和想法，从而可以在以后轻松维护代码 16 | - 鼓励相关学习对方的长处和有点和高效迅速完成代码评审 17 | - 可以被用来确认自己的设计和实现是一个清楚的和简单的设计 18 | 19 | ## 解决代码冲突 20 | 21 | 如果代码评审中有任何冲突，开发人员和评审人员都应该首先根据[代码开发者指南](../Developer/index.md)和[代码评审者指南](../Reviewers/index.md)中其他文档的内容，尝试达成一致意见。 22 | 当很难达成一致时，开发者和评审者不应该在代码评审评论里解决冲突，而是应该召开面对面会议或者找个权威的人来协商。（如果你在评论里协商，确保在评论里记录了讨论结果，以便日后其他人翻阅。） 23 | 如果这样都解决不了问题，那解决问题的方式就应该升级了。通常的方式是拉着团队一起讨论、让团队主管来权衡、参考代码维护者的意见，或者让管理层来决定。**不要因为开发者和评审者不能达成一致而把变更一直放在那里。** 24 | 25 | ## 增加评审模版 26 | 27 | 评审模版应包含简介，主要变更，相关Issue/PRD 28 | 29 | ## 利用 Gitlab 做代码评审 30 | 31 | 常见的一些代码评审工具 32 | 33 | - Phabircator（Facebook) 34 | - Gerrit (Google) 35 | - Gitlab / Github 36 | 37 | ### 提交代码评审之前 38 | 39 | - 确保经过设计评审，架构和总体技术方案经过论证 40 | - **MR**描述清楚业务功能，附上原型，主要变更，问题链接 41 | - 充分自测或核心模块经过单元测试 42 | - 代码经过 Gitlab CI 的静态检查 43 | - 提交范围尽可能小和完整；不要一次性提交大量不相关的功能代码，把评审时间控制在20min以内 44 | - 按照 Git Commit 提交规范进行提交 45 | - 不阻塞他人的工作，尽快响应他人的代码评审请求 46 | - 如果某个**MR**紧急，可以告知 Reviewers 47 | 48 | ### 一次完整的代码评审 49 | 50 | - 提交合并请求**MR** 51 | - 触发代码评审提醒和 CI pipeline 执行 52 | - 代码评审者执行评审过程，代码评审者可以提交评论，其他人也可以参与针对问题进行持续跟进，一个**MR**手动设置多人参与CR 53 | - 代码评审开发者收到评审意见，修改代码，回复评论，关闭问题 54 | - 代码评审者确认问题是否修复，允许合并 55 | 56 | ### 代码评审流程 57 | 58 | ![代码评审流程图](../../graph/code-review.svg) 59 | 60 | ### 代码评审者应该关注什么 61 | 62 | - **代码风格**: 代码风格是否遵循数栈代码风格指南? 63 | - **设计**：配置、接口类的设计问题（合理性、友好性)？错误、重复的 API 调用或者封装？ 64 | - **功能性**: 代码功能是否和开发者预期一致？逻辑的遗漏缺陷？ 65 | - **复杂性**: 代码能不能更简单？其他开发者能否快速理解并在未来很容易地使用这段代码？ 66 | - **测试**: 是否缺少应有的单元测试或者文档 67 | - **命名**: 开发者有没有正确地对变量、类、方法等命名？ 68 | - **文档**: 开发者是否更新了相关文档？ 69 | - **注释**：无用的代码或者注释 70 | 71 | 参考 **[代码评审者指南](../Reviewers/index.md)** 获取更多信息。 72 | 73 | ### 挑选最适合的代码评审者 74 | 75 | - 优先选择熟悉该业务域，技术域的开发，事先定好人选 76 | - 指定模块最近参与修改的单个或多个同学作为 Reviewer 77 | - 指定参与相关模块讨论和设计过的人作为 Reviewer 78 | - 指定项目核心开发者作为 Reviewer 79 | - 如有必要，Reviewer 可分配给多个相关人 80 | 81 | ### 你需要知道的**MR**流程 82 | 83 | - New Merge Request 84 | 85 | ![新增MR](../../graph/new_MR.gif) 86 | 87 | - review Merge Request 88 | 89 | ![评审MR](../../graph/review_MR.gif) 90 | 91 | - Merge Request 92 | 93 | ![合并MR](../../graph/merge_MR.gif) 94 | 95 | ### 开发者需遵循的工程规范 96 | 97 | - Git Workflow：[Git Workflow](https://dtstack.yuque.com/rd-center/sm6war/vzg2xd) 98 | - Git Commit: [Git Commit](https://dtstack.yuque.com/rd-center/sm6war/dnt36o) 99 | - SemVer：[SemVer](https://dtstack.yuque.com/rd-center/sm6war/cmdl2z) 100 | - CSS 编码规范(SASS/BEM)：[SASS/BEM](https://dtstack.yuque.com/rd-center/sm6war/clgpb7) 101 | - BEM 使用帮助：[BEM 使用帮助](https://dtstack.yuque.com/rd-center/sm6war/wb76lx) 102 | - Code Style Guide(https://github.com/DTStack/Code-Style-Guide) 103 | 104 | ### 开发者需要知道的CI/CD流程 105 | 106 | - Static Checking 107 | - ESlint 108 | - Type Checking 109 | - MDLint 110 | - Prettier 111 | - Stylelint 112 | - Unit Testing 113 | - Build 114 | - Lock Yarn 115 | - Unify yarnrc 116 | - Migrate gitlab-runner to Jenkins 117 | 118 | ### 配合工具最佳 119 | 120 | 为了提升工作效率，我们可以在我们的编辑器工具中安装相关的各种插件，提升整个评审效率，由于我们大部分同学都在使用 VSCode，这里我就列举部分插件以作参考： 121 | 122 | - ESLint 代码静态检测, 解决基本的代码风格不统一的问题，避免一些低级 bug。当然 ESLint 最好集成到开发构建环节中去 123 | - GitLens 非常好的 git 可视化管理插件 124 | - Gitlab MR 协助快速创建**MR**请求 125 | 126 | ## 参见 127 | 128 | - **[代码评审者指南](../Reviewers/index.md)**: 代码评审者的详细指南。 129 | - **[代码开发者指南](../Developer/index.md)**: 提交变更评审的开发者的详细指南。 130 | - **[代码评审机制保障](../Mechanism/index.md)**: 代码评审机制保障 131 | -------------------------------------------------------------------------------- /review/Developer/index.md: -------------------------------------------------------------------------------- 1 | # 代码开发者指南 2 | 3 | ## 复杂需求先设计再编码 4 | 5 | 有些新人发现自己的代码提交**MR**后，会收到一堆的代码评审意见，必须要做大量的改动。这多半是因为在开始做之前，没有做好设计，做出来后才发现问题很多。建议在做一个新功能之前，写一个简单的设计文档，表达清楚自己的设计思路，找资深的先帮你做一下设计的审查，发现设计上的问题。设计上没问题了，再着手开发，那么到评审的时候，相对问题就会少很多 6 | 7 | ## 代码在提交代码评审之前，作者要自己先评审和测试一遍，保证发布代码的易读性 8 | 9 | 我在做代码审查的时候，有时候会发现一些非常明显的问题，有些甚至自己都没有测试过，就等着别人代码评审和测试帮助发现问题。这种依赖心理无论是对自己还是对团队都是很不负责任的。一个好的开发人员，代码在提交代码评审之前，肯定是要自己先评审一遍，自己把基本的测试用例跑一遍的 10 | 11 | ## **CR**要小 12 | 13 | 代码评审效果和质量与**CR**代码量成反比，每次**CR**代码量小一些，看起来速度快，又不至于失去耐心，所以要经常进行代码评审，但是每个**CR**代码量要少，我建议要少于 200 行/**CR** 14 | 15 | ## 充分描述改动上下文 16 | 17 | 写好简介，主要变更，以及附上原型和问题链接，每个**MR**只讨论一件事，逻辑较为复杂，需要提供简要的功能描述和截图 18 | 19 | ## **WIP** 20 | 21 | 如果你有个改动很大的 **MR**，可以在写了一部分的情况下先提交，但是在标题里写上 WIP，以告诉项目维护者这个功能还未完成，方便维护者提前 review 部分提交的代码 22 | 23 | ## 什么时候才能合并代码 24 | 25 | + 解决所有的 discussions（Gitlab 设置） 26 | + 至少 1 个 reviewer 同意才能合并 27 | -------------------------------------------------------------------------------- /review/Mechanism/index.md: -------------------------------------------------------------------------------- 1 | # 代码评审机制保障 2 | 3 | ## 数据衡量 4 | 5 | + 通过 Gitlab 统计代码评审 MR 数，MR comments 数，以及线上问题产品迭代缺陷数 6 | + 可与@偷天团队合作 7 | 8 | ## 定期检查回顾 9 | 10 | 定期回顾和总结 Code Review 执行情况 11 | 12 | + 项目总结 13 | + 团队周会回顾 14 | 15 | ## 激励 16 | 17 | 由于代码评审本身跟人的经验或者意识都有很大关系，很多时候我们会为调动不起开发同学的积极性而烦恼，所以为了让大家更好的参与这个活动，我们一般都需要制定相应的激励机制 18 | 19 | + 通过数据分析，找出表现突出的员工（如提交次数，review 次数，comments 量), 给予鼓励（礼品，书籍） 20 | + 找出优秀的代码进行周分享 21 | + 对于表现欠佳的员工，TL 进行适度的负向激励 22 | + 跟绩效挂钩 23 | 24 | ## 责任归属 25 | 26 | + 需求合理性，进入代码评审的需求都是充分论证且合理的，这是需求评审阶段应该做的事情 27 | + 设计评审，应在设计阶段进行，比如设计思路，业务系分，可能遇到的困难及解决方案等 28 | + 局部评审不讨论全局问题，保障每个**CR**只涉及当前评审相关，试图在碎片化信息中总结全貌比较低效其次也会影响评审人开发进度 29 | -------------------------------------------------------------------------------- /review/Reviewers/Checklist.md: -------------------------------------------------------------------------------- 1 | # 代码评审应该关注什么 2 | 3 | ## 功能性 4 | 5 | + 开发者在这个变更中想做什么？（这里”用户“是指受变更影响到的实际用户，和将来会使用到这些代码的开发者) 重要的是，我们希望开发者能充分测试代码，以确保代码在代码评审期间正常运行。站在用户的角度，确保你正在看的代码没有 bug。 6 | 你可以验证变更，尤其是在有面向用户的影响时，评审者应该仔细检查整个变更。有时候单纯看代码很难理解这个变更如何影响到用户，这种情况下如果你不方便自己在**MR**中打补丁并亲自尝试，你可以让开发者为你提供一个功能性的示例。 7 | + 确保功能对比原型无遗漏 8 | + 不应存在分支/场景/需求错漏 9 | 10 | ## 设计 11 | 12 | + 代码评审中最重要的一个点就是把握住变更中的整体设计。评审此次变更设计的影响范围及会不会影响到其他功能？现在是否是添加整个功能的恰当时间？ 13 | + 配置、接口类的设计问题（合理性、友好性)？错误、重复的 API 调用或者封装？ 14 | + 函数与模块拆分是合理的？ 15 | 16 | ## 复杂性 17 | 18 | + 变更是否比预期的更复杂？检测变更的每个级别，是否个别行太复杂？功能是否太复杂？类是否太复杂？”复杂“意味着代码阅读者很难快速理解代码，也可意味着开发者尝试调用或修改此代码时可能会引入 bug。 19 | + 一个典型的复杂性问题就是**过度设计**，当开发者让代码变得更通用，或者增加了许多当前不需要的功能时，评审者应该额外注意是否过度设计。鼓励开发者解决现在遇到的问题，而不是揣测未来可能遇到的问题。未来的问题应当在遇到时解决，到那个时候你才能看到问题本质和实际需求。 20 | + 尽可能使用公共组件，避免造轮子 21 | 22 | ## 单元测试 23 | 24 | + 代码有适当的单元测试，测试逻辑设计良好 25 | + 核心模块单测通过率 100% 26 | 27 | ## 命名 28 | 29 | + 开发人员是否使用了良好的命名方式？好的命名要能够充分表达一个项（变量、类名等）是什么或者用来做什么，但是又易读。 30 | + 各类命名是易读的，函数命名语义化，且清晰无歧义 31 | 32 | ## 风格 33 | 34 | + lint 通过率 100% & lint 忽略项是合理的 35 | + 主流语言遵循数栈编码风格指南，确保变更遵循了这些风格规范 36 | + 开发人员不应该将风格变更与其他变更放在一起，会降低变更设计评审效率 37 | 38 | ## 注释 39 | 40 | + 注释清晰明了实用，通常解释清楚了为什么这么做，而不是做了啥 41 | + 注释是清晰，完善且与代码相符的 42 | 43 | ## 代码细节 44 | 45 | + 不应存在测试用途代码 46 | + 不应存在不必要的第三方库引用 47 | + 不应存在明显的安全漏洞(XSS/CSRF/SQL 注入) 48 | + 本次**MR**的 TODO/TOFIX 处理完毕 49 | 50 | ## 评审效率 51 | 52 | + **MR**的说明是清晰且完善并完整交代改动背景, 上下文的 53 | + 被评审规模控制在 3 次提交内，不超过 200 行修改 54 | 55 | 下一篇：[代码评审的步骤](navigate.md) 56 | -------------------------------------------------------------------------------- /review/Reviewers/comments.md: -------------------------------------------------------------------------------- 1 | ## 怎么写代码评论 2 | 3 | - 团队协作 4 | 在一个团队工作和气很重要，使用请求语气，而非命令语气，不要使用“你”这样的用词，尽量改成：我们可以用更清晰的变量名 5 | - 提出建设性意见，如果你觉得有更好的方案请提出说明，而不是只是给模糊的观点 6 | 在代码评审中经常会发现写的不好的地方，如果你有更好的方法，欢迎提出来！首先能改进这个**MR**的代码，其次能体现你的能力，团队应该定期对这种提出好的解决方案的同事进行奖励 7 | - 每个**MR**至少给一条正面评价 8 | 代码评审本意是改善代码质量，增强团队成员之间的沟通，但是我一提交代码就有人说我写的垃圾，这很打击自信心，也不利于团队成员和平相处。代码有问题，指出问题是必须的，要实事求是，但是有的时候也需要给队友一点鼓励 9 | - 存在反复的同类问题只有限度的反馈，标识出请修改同类问题 10 | - 不要在**MR**中讨论需求，review 就是 review 11 | 不要在代码评审里搞别的，有需要就另安排时间进行，要明确代码评审是完善代码，不是需求和功能讨论，始终要以代码质量为中心 12 | 13 | ## 处理代码评审中的反驳 14 | 15 | 有时开发者会在代码评审中反驳你，他们可能不同意你的意见，或者抱怨你太严格了。 16 | 17 | - 谁是谁非 18 | 有时候要让开发者接受，你得花很多时间反复解释，但始终确保该有的礼貌，并让开发者知道在知道他们了什么，即便是你不同意。 19 | - 稍后解决 20 | 一种常见的反驳原因是开发者希望能尽快完成任务。他们不想一轮又一轮地做代码评审，然后就会说他们会在后续**MR**中处理这些问题，你只需要通过就行。然而，经验告诉我们原始**MR**通过之后拖的时间越久，就越不可能修复。除非开发者在当前**MR**通过后立马修复，否则他们就不可能修复。这并不是开发者不负责任，而是因为他们有好多工作要做，而修复工作也会因为工作压力而被遗忘。所以最好坚持让开发者现在就在MR中处理掉这些问题，“留着以后清理”是一种不可取的方式。 21 | 如果**MR**中引入了新的复杂性，提交之前必须清理掉，除非是紧急情况。如果**MR**中暴露出一些目前还无法定位的问题，开发者应该记录下这些bug，并将其分配给他们自己，确保这些问题不会被遗忘。他们还可以在代码中加入 TODO 注释，指向已经记录好的 bug。 22 | - 抱怨太严格 23 | 不要在意，最终开发者在看到产出的优质代码时会理解严格代码评审带来的价值 24 | -------------------------------------------------------------------------------- /review/Reviewers/index.md: -------------------------------------------------------------------------------- 1 | # 代码评审者指南 2 | 3 | 本节中介绍了基于长期经验总结的代码评审最佳实践。所有内容都在同一个章节里，但被分为了好多子章节。虽然你不必通读一遍，但认真看一遍对你自己和整个团队都会有很大的益处。 4 | 5 | - [**代码评审应该关注什么**](Checklist.md) 6 | - [**代码评审步骤**](navigate.md) 7 | - [**怎么写代码评论和处理代码评审中的反驳**](comments.md) 8 | 9 | ## 代码评审注意事项 10 | 11 | - 尽快评审，不要拖延 12 | - 大的变更 13 | 如果有人给你提交了一个非常大的代码评审，你也不确定你有时间看，你最好建议开发者把**MR**拆分成几个小的部分，分多次代码评审，而不是一次性全部提交上来，而且拆分也有利于评审者。 14 | 作为评审者，你的目标之一是在不牺牲代码质量的前提下，不阻碍开发者的进程或者尽可能让他们向前推进 15 | - LGTM 16 | 通过一些术语向开发者表示允许合并 17 | -------------------------------------------------------------------------------- /review/Reviewers/navigate.md: -------------------------------------------------------------------------------- 1 | # 代码评审步骤 2 | 3 | ## 全局看下变更设计 4 | 5 | 阅读明白变更大体内容。这些修改是否有意义？首先如果这个修改不应该有，请立刻说明为什么这些修改不应该有。当你因为这个拒绝了这次改动提交时，告诉开发人员该怎么去做是非常好的。 6 | 最好在做大量工作之前告诉人们“不必做”，因为现在要将其丢弃或彻底重写。建议让代码开发者提一个**WIP**，如果发现设计偏离，提早向代码开发者指出，如果是复杂功能设计，最好让开发者写个技术方案。 7 | 8 | ## 检查变更的主要部分 9 | 10 | 检查变更设计的主要部分，通常来说一次变更设计最复杂的部分应该是逻辑修改最多的文件，如果此次变更涉及模块太多，建议让代码开发者拆分**CR**，代码量定义 >200 的差异变更算作大的**CR**，大的**CR**要做拆分，小的**CR**评审起来效率更高。只有**CR**拆分合理及细致，才能区分出主要 11 | 部分的变更，如果您发现变更的这一部分存在一些主要的设计问题，则即使您现在没有时间审查变更的其余部分，也应立即写下这些评注。实际上，检查其余的变更可能会浪费时间 12 | 13 | 立即写下这些主要设计评注非常重要有两个主要原因： 14 | 15 | - 开发人员通常会发送给审核者一个**MR**，然后在等待审核时立即基于该**MR**进行新工作。如果您正在审查的**MR**中存在重大设计问题，那么他们也将不得不重新设计其以后的**MR**。你能在他们做太多无用功之前制止他们。 16 | - 重要的设计变更比小的变更需要更长的时间。开发人员几乎都有截止日期；为了在截止日期之前完成工作，并在代码库中保留高质量的代码，开发人员需要尽快开始**MR**的所有主要的重做。 17 | 18 | ## 依次阅读变更的其他部分 19 | 20 | 确认完此次变更的主要部分后，剩下的部分就是根据自己的时间安排评审，但是必须在开发人员截止日期之前完成评审，为代码开发者预留好修复的时间。 21 | 22 | 下一篇：[如何在代码评审中写评论](comments.md) 23 | -------------------------------------------------------------------------------- /review/index.md: -------------------------------------------------------------------------------- 1 | # 代码评审指南 2 | 3 | ## 代码评审是什么 4 | 5 | 代码评审是一些人提交一些代码片段，供另外一些人审阅的流程。在数栈，我们都是通过代码评审来保证代码和产品的质量。这篇文档是对数栈评审流程和策略的权威描述 6 | 7 | ## 为什么要做代码评审 8 | 9 | + 提升代码质量，代码可读性，可维护性, 发现潜在缺陷&风险，避免一些低级的 bug 在代码部署到测试环境才被发现 10 | + 从团队规范角度，由于新成员的加入提高了团队编码风格的差异性，保证团队规范的执行 11 | + 团队成员交叉代码评审无统一评审标准；其次有些他人写的业务逻辑，在交叉维护时，需要花更多的时间上手 12 | + 促进人才成长，对新成员的代码质量和成长负责，提升整个团队的技术实力 13 | + 知识传递，人员备份，保证有人离职后其他人能快速接手 14 | + 在不是很了解现有项目的基础上，实现的新功能代码会产生冗余 15 | 16 | ## 代码评审能带给我们什么 17 | 18 | ### 团队知识共享 19 | 20 | 一个开发团队中，水平有高有低，每个人侧重的领域也有不同。怎么让高水平的帮助新人成长？怎么让大家都对自己侧重领域之外的知识保持了解？怎么能有人离职后其他人能快速接手？这些都是团队管理者关心的问题。而代码审查，就是一个很好的知识共享的方式。 21 | 通过代码审查，高手可以直接指出新手代码中的问题，新手可以马上从高手的反馈中学习到好的实践，得到更快的成长，尤其针对同一项目多人负责的情况，便于团队成员相互学习不同模块的代码。 22 | 23 | ### 提升代码质量 24 | 25 | 代码质量可以从两个维度来理解，一是可读性，一是缺陷情况，谷歌最早引入代码评审的初衷是保障代码易读性，代码也是一种资产，具有“流通性”，通常会面临 3～5 年的迭代维护，期间会面临人员更替，其他人参考引用的情况，在基于众多的技术手段及流程规范中，相较于其他基于结果进行验证的质量保证的手段，Code Review 的关注点更加广泛全面，能够发现程序逻辑以外的设计，性能，规范等多方面的问题。 26 | 27 | ### 便于团队规范落地和执行 28 | 29 | 每个团队都有自己的代码规范，有自己的基于架构设计的开发规范，然而时间一长，就会发现代码中出现很多不遵守代码规范的情况，有很多绕过架构设计的代码。如果这些违反规范的代码被纠正的晚了，后面再要修改就成本很高了，而且团队的规范也会慢慢的形同虚设。 30 | 通过代码审查，就可以及时的去发现和纠正这些问题，保证团队规范的执行 31 | 32 | ### 促进人才成长 33 | 34 | 如何提升产品业务代码质量，促进一线研发人员的成长，一直是一个避不开的话题，我们一线的技术团队，按照层级呈现金字塔型，如果团队核心骨干人员能参与到团队日常的架构评审，设计评审及代码评审，一定可以切切实实的帮助到其他研发人员的成长，不论是新人的融入还是处于瓶颈期的开发人员。 35 | 36 | ### 培养技术情怀 37 | 38 | 虽然我们都渴望工程师能够热爱自己所从事的工作和技术，但这只是我们期望的结果，但是可以通过点滴的代码评审培养工程师对代码关注和思考多了也是一个长期受益的事情， 39 | 40 | + 热爱：对于一线工程师来说，每天产出的是一行一行的代码，但是如果有人（非机器）能对自己深思熟虑并且精心雕琢过的代码给予正向的激励，那其实是会提升工程师对代码的热爱的 41 | + 思考：其次也会鼓励工程师主动式思考，比如怎么写效率高且更具备可扩展性，换个角度想一一下，假如你知道你写的每一行代码，每一次提交，都会被大家看到，都会有人审核，那么其实在写的时候，工程师就会多想一下，无形之中通过流程促使工程师在日常产品开发中养成了主动思考的习惯 42 | 43 | ## 代码评审 1.0 阻碍 44 | 45 | + 资深的工程师偏少 46 | + 有单独负责项目的情况 47 | + 执行力不足 48 | + 缺少明确的 CheckList 49 | 50 | ## 代码评审共识 & 约定 51 | 52 | 不同团队对代码评审有着不同理解，我们需要就实现我们的代码评审先达成共识，并且以下所有的规则都是围绕这份共识设计 53 | 54 | + 让代码评审回归 55 | 编码设计&易读&缺陷等, 软件质量本身是系统治理，不期望代码评审能解决所有问题 56 | + 代码评审对软件质量保障有长远且显著的正面效果，不期望和评价短期效果，是一个长期坚持能看到效果的代码管理手段 57 | 58 | ## 如何做代码评审 59 | 60 | + 把代码评审作为开发流程的必选项而不是可选项 61 | + 把代码评审变成一种开发文化而不仅仅是一种制度 62 | 63 | [如何做代码评审](CodeReview/index.md) 64 | --------------------------------------------------------------------------------