为团队引入「代码规范」的建议与心得

[shot]

为团队引入「代码规范」的建议与心得

建议步骤

1. 了解业界主流的代码规范（如 google style），结合团队痛点仔细分析比对
2. 了解支持规范检测的自动化工具（ linter 、compiler 、test ）
3. 选取小部分支持自动化工具检测的规则，工具引入开发环境，配置纳入项目源代码管理
4. 修改工具检测出的问题，签入主分支
5. 向团队宣贯规范条文（开源工具文档 or 简化的内部规范文档）、培训使用方法，要求一周内学习应用
6. 一周后，在持续集成环境中增加代码规范检测步骤，CI 不通过不做 code review 不合并到主分支
7. [长期]根据团队状况，持续增加规范条目，同步更新工具、配置、文档

背景 （ battle with 大学同学量化金融巨子 L ）

L：有没有关于 C++/python 函数、变量命名规范的，比较 general 的简约的一套标准

L：麻烦分享下实用或入门的帖子

L：主要是项目合作，还是要稍微共识规范一点

I：（贴 Google 搜索 "google c++ style" 截图）

I：搜索引擎这么好，你为什么不用？

L：你的这个过于宽泛，我不需要这么系统的

L：我需要的就是个入门的

L：而且我之前看到的 c++ 和 python 规范还不一样

I：根据你们团队情况裁剪定制呀

L：那我等于先要成专家啊

L：我就是这里找专家，高屋建瓴给指条小路的

I：不然你想一天速成？

I：那就花钱找专家呗

（敲上文所述「建议步骤」中）

你被 L 移出群聊

心得

• 代码规范非常重要，能保障团队的代码质量在一个 明确设定的水平线 上。
• 代码规范属于 软件工程化体系 的重要组成部分，需要与团队组织、知识传递、工具集成、开发流程等其它各部分密切配合，才能充分发挥作用，切实提高项目质量。
• 代码规范是 最佳实践 不是行业标准，没有放之四海皆准的办法；需结合语言特性、行业共识、团队能力水平、项目质量要求等定制切入。
• 引入代码规范不是一个轻松的过程，如果团队认知不足甚至会在开始阶段抵触，不要期望一蹴而就。
• 能使用自动化工具检测的规范才是好规范，才能快速宣贯应用，平缓学习曲线，避免高成本人肉检测。
• Java 的工程化工具非常丰富（ checkstyle 、spotbugs 、pmd 、compiler 、archunit 、sonarqube ），希望别的主流语言也能赶上。
• 主流语言都有业界公认的通用规范，不要闭门造车，可以有选择裁剪组合，持续增强。
• 没有自动化工具支持的规范，个人认为没必要纳入规范，因为没办法检测量化，且应该不是业界普遍痛点。
• （接上条）如果确实很痛很痛，那就想办法自己写一个工具 /脚本，实现自动化检测（夸一下 java 的 archunit ）。
• 自动化检测工具需要支持本地化运行，最好有 IDE 插件实时检测；如果只支持云端检查非常影响开发效率和体验。
• 自动化代码检测很有用，但不能检查业务盲点和逻辑错误，也不能避免小众错误；需要和 unit test 及 code review 配合。

亲身案例一： 加入前公司 A 启动新项目

1. 启动阶段直接在项目框架中配齐 checkstyle 、spotbugs 、pmd ，纳入 CI 。
2. 每个新成员入职时，介绍代码规范和工具。
3. 在其第一第二周碰到问题时，帮助分析解决。
4. 两周后，均能熟练掌握规范和工具，提交代码符合规范要求。

亲身案例二：加入前公司 B 重构（ sh*t mountain ）老项目

1. 引入 spotbugs ，与团队做知识分享，重点介绍其检测出的安全隐患与性能隐患。
2. 搭建 jenkins 环境，配置项目 pipeline ，spotbugs 报错不阻塞。
3. 全面修改 spotbugs 问题，签入主分支。
4. 第一周持续关注新引入 spotbugs 问题，一对一帮扶。
5. 修改 jenkins pipeline 配置，报错阻塞构建。
6. 逐步增加规则，并引入配套的 checkstyle 、pmd 、sonarqube 等工具。
7. 引入代码规范后，择期分析统计生产环境出现的与代码质量不佳相关的缺陷数，比较引入规范前的指标情况，向团队 /上级 /合作部门 /客户展示汇报，体现其价值。

亲身案例三：前公司 C （大厂）推广自研 CI 服务

1. 公司某团队魔改 jenkins 和 sonarqube ，作为内部标准要求所有项目启用。
2. 魔改 jenkins 提供的基础 docker 镜像非常有限，无一支持我团队项目的 C++ 运行时；反复沟通后该团队手工添加基础镜像解决，但后继每次镜像升级仍需人工操作。
3. 魔改 sonarqube 规则，且不提供开发环境相应工具 /配置 /脚本；只能每次代码提交后等云端执行结果，每次耗时 > 4 minutes ，有时一次功能代码要修改提交三四次才能通过检测。

blog 原文

为团队引入「代码规范」的建议与心得

[shot]

@wu67 #13

你举的「逻辑写法」内容应该也能工具化规范化解决。

> 遍历数组都能写出 7 8 种写法
eslint-plugin-github 有 "Prefer for...of statement instead of Array.forEach" 规则。
https://github.com/github/eslint-plugin-github/blob/main/docs/rules/array-foreach.md

> 还有在非变异方法里面通过引用改变原数组值的
似乎 eslint 的 no-param-reassign 搞不定这种情况，要上 typescript 的 readonly T[]
https://eslint.org/docs/2.0.0/rules/no-param-reassign
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#improvements-for-readonlyarray-and-readonly-tuples

---

有些代码规范的工具化，需要引入新工具甚至新语言（ javascript → typescript ），成本不菲。
这就引申出进一步的问题：如何平衡代码规范和开发体验？

引入代码规范最好能循序渐进持续增强，切忌大破大立，很考验领导者的平衡艺术。

[shot]

@evilStart #19

确实是反面案例，用以佐证我的观点：
自动化检测工具需要支持本地化运行，最好有 IDE 插件实时检测；如果只支持云端检查非常影响开发效率和体验。

[dany813]

这玩意，刚开始有人会按照规定来，时间长了就不行了

[wjx0912]

文笔不错，赞一个

[bigmao0720]

代码规范重要吗？看情况，对技术重要，它意味着品味，共识和效率；在商业型眼里可能不那么重要，因为很多情况下它并不会多赚钱。在中小厂以及大厂的某些部门里，它是 nice to have, 想要做到一个是慢慢来，润物细无声，另一个是用商业的方式去推技术的前进。

[arthas2234]

让人主动去看代码规范基本上没啥效果
最简单粗暴的就是装个 guideline 插件
定期 analyze code ，warning 数和评比挂钩

[lmmlwen]

别人的生意而已

[RiceNoodle]

我们团队这里，合并前的 PR 必须要有一个 approval 。
然后 PR 的时候 CI 会执行 lint ，lint 检查没通过的话，没人会给 approval 。
lint 采用哪些规则是开会讨论过的，先用简化版本，然后慢慢增加。

[siteshen]

个人觉得 google style 很烂，各方面的烂。我现在使用的规范如下：

Python: black
JavaScript: Prettier
C++: clang-format (LLVM + ColumnLimit: 100)
Go: gofmt

至于 codelint ，doc 相关的都会禁用，其他基本保持默认。

[jin5354]

我只有个人项目加规范玩玩。
公司项目规范加不加卵用都没，因为在紧张的排期面前，没啥能比按时交付更重要，粗糙就粗糙了，天天 -- no-verify ，谁也无力回天，推不动的，能让公司把排期延长吗？

[Jero]

可以考虑使用[代码分析平台]( https://github.com/Tencent/CodeAnalysis)持续扫描，目前已经集成了业界常见的代码扫描工具