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

[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 原文

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

[fengzl]

是 battle with 吧

[shot]

@fengzl #1

已修正，谢谢提醒。

[FrankHB]

这种东西，有确保执行力专家的就直接让专家起草，否则放 wiki 页面找个召集人让项目成员一起写，免得规范没讲清楚，style 上就先扯皮了。
负责代码层次上具体规范和往上提供工程支持明显是两码事，职责得分清。

主流大厂也不见得质量好哪去，说好听点是妥协，直说就是菜。

比如，Google C++ Style （官方叫 Guideline ）这种几乎每一条都有槽点到跟 anti pattern 都没差多少的，如果看不出来问题，那就足够说明 C++不怎么熟悉，不能胜任一般意义的起草规范的工作。
其实我是觉得至少要能发现 GSL 的大部分缺点才算得上是规范管理专家的入门水平。Google 那种明显属于怂了不合格；具体点，如禁用异常，理由是不信大部分员工会用好……（这么基础的东西，啧啧）。

这种规范，有时候明文还不如事实标准慢慢磨（ copyright notice 之类法务要求的另说）。

而要帮助提供工具，设计流程之类，自己怎么方便怎么发挥，就没这个限制。

[jorneyr]

规范定制容易，怎么执行才是核心。
员工都是怎么舒服怎么来，要想执行，技术领导自己先做榜样，强制执行，否则就滚蛋。至少以前我是这么干才推行起来的，靠员工自觉，同级员工 Code Review 就是个笑话。

[zzwyh]

我们领导都直接把 eslint 给关了，我也是服了

[bruce0]

我同事写 go 有时候提交代码都不 fmt, 我他妈的都想骂他, 但是都是同级的, 差不多时候来公司的, 直接说他可能会让他脸上挂不住, 我也就懒得说了

[l00t]

提问，假如你用到了第三方的代码，你需要把第三方的代码也改成符合你的规范吗？

[shot]

@jorneyr #4

> 规范定制容易，怎么执行才是核心。

非常同意。这也是我再三强调自动化工具及持续集成的原因。

员工可以就使用过程中的不便提意见，需要带明确的反对理由、业界实践、修改建议。
未被采纳前就要按现在规范严格执行。

[ychost]

一般是要求 eslint 、code Style 等各个语言的插件来保证的，主要是格式化之后必须得一样的，避免每次因格式化带来的不必要变更，影响 CR 效率

[shot]

@FrankHB #3

你的关注点已经是「规范的合理性」了，这通常是精英级团队才会考虑的问题。
精英团队完全可以自行裁剪组合甚至新建能符合自己团队项目情况的规范。

对于平均水平团队，初次引入「代码规范」的情况来说，有规范总比没有规范好。
不喜欢 google style 可以找找别的。

[ChefIsAwesome]

跟不懂规范意义的人谈规范没用。强制执行几天，就像楼上说的，他们自己把 lint 之类的关了。
很多人说“业务复杂，时间太紧，只能写出来屎一样的代码”，可实际上，你问他们，怎么写出来不像屎一样的代码，他们根本不知道。
写代码就像写文章，要反复推敲，斟酌文字。只有熟练了微重构代码的技能，才能在时间紧张时，写出不烂的代码。
只可惜“如何写好代码”，学校不教，面试不问，工作不查。

[shot]

@l00t #7

你是说直接复制粘贴第三方源代码进项目的情况吧？

两种处理方式：
1. 所有第三方源代码文件置于一个特定目录，在工具里配置不检测这个目录的内容。

2. 粘贴复制后修改使其符合规范
2.1 粘贴复制 git commit -m 'Add a class for xxx, copied from https://xxx'
2.2 修改使符合规范 git commit -m 'refactor it to follow our code style'

[wu67]

我觉得, 要处理的话, 应该先把 ‘代码规范’ 这个命题理清. 细分的话, 是可以分成 代码风格 和 逻辑写法 这两个领域的.
前者可以通过各种工具及 ide 实现;(例如前端的 eslint idea 全家桶的代码风格格式化). 后者是逻辑写法, 举个前端的例子, 不少干了几年活的搬砖工, 遍历数组都能写出 7 8 种写法, 还有在非变异方法里面通过引用改变原数组值的...看了就血压拉满.

正经来讲, 应该先把前者普及完毕, 然后再去通过技术分享、review 之类的方式提高团队的编码水平, 这才能形成后者的规范、或者说向某个规范靠齐.

[vicalloy]

加 pre-commit ，提交前自动格式化。大多情况下个人偏没啥必要，也不会增加员工工作量。

[SakuraPGH]

[代码规范] 这个问题感觉可以需要提出一整个解决方案出来：
- 环境准备：
1. 工具统一，开发格式化插件统一，规则统一
2. CI 集成
3. 开会培训 Code review

- 执行准备：
1. 奖励机制
2. 惩罚机制

[missdeer]

对 6 楼的遭遇深有同感，现在我都不敢说了

[shot]

@ChefIsAwesome #11

> 可实际上，你问他们，怎么写出来不像屎一样的代码，他们根本不知道。
是的，这对很多团队来说属于 "unknown unknowns"。
即使感觉到了痛点，也总想走捷径，不愿意花精力去学习了解（就像我的巨子同学）。

> 只可惜“如何写好代码”，学校不教，面试不问，工作不查。
哈哈，我面试的最后一个问题都是「对于提高团队的整体代码质量，你有什么经验和心得？」。
进而引出对源代码检测、单元测试、code review 的讨论，判断他的技术追求和团队适性。

[dream4ever]

世界上有两种人，一种是对美有追求的人，另一种没有追求，体现在这个行业，如果可以，尽量不要和追求不相同的人共事

[evilStart]

你说的亲身案例 3 难道不是一个反面案例吗？糟糕的 DevOps 支持很影响开发效率

[Huelse]

我的意见在于这类问题归根结底还是人的问题

一定要多交流，有障碍就必定有问题，需要有个组长之类的存在主动调动成员之间的沟通与学习

[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)持续扫描，目前已经集成了业界常见的代码扫描工具