为团队引入「代码规范」的建议与心得
建议步骤
- 了解业界主流的代码规范（如 google style），结合团队痛点仔细分析比对
- 了解支持规范检测的自动化工具（ linter 、compiler 、test ）
- 选取小部分支持自动化工具检测的规则，工具引入开发环境，配置纳入项目源代码管理
- 修改工具检测出的问题，签入主分支
- 向团队宣贯规范条文（开源工具文档 or 简化的内部规范文档）、培训使用方法，要求一周内学习应用
- 一周后，在持续集成环境中增加代码规范检测步骤，CI 不通过不做 code review 不合并到主分支
- [长期]根据团队状况，持续增加规范条目，同步更新工具、配置、文档
背景 （ 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 启动新项目
- 启动阶段直接在项目框架中配齐 checkstyle 、spotbugs 、pmd ，纳入 CI 。
- 每个新成员入职时，介绍代码规范和工具。
- 在其第一第二周碰到问题时，帮助分析解决。
- 两周后，均能熟练掌握规范和工具，提交代码符合规范要求。
亲身案例二：加入前公司 B 重构（ sh*t mountain ）老项目
- 引入 spotbugs ，与团队做知识分享，重点介绍其检测出的安全隐患与性能隐患。
- 搭建 jenkins 环境，配置项目 pipeline ，spotbugs 报错不阻塞。
- 全面修改 spotbugs 问题，签入主分支。
- 第一周持续关注新引入 spotbugs 问题，一对一帮扶。
- 修改 jenkins pipelne 配置，报错阻塞构建。
- 逐步增加规则，并引入配套的 checkstyle 、pmd 、sonarqube 等工具。
- 引入代码规范后，择期分析统计生产环境出现的与代码质量不佳相关的缺陷数，比较引入规范前的指标情况，向团队 /上级 /合作部门 /客户展示汇报，体现其价值。
亲身案例三：前公司 C （大厂）推广自研 CI 服务
- 公司某团队魔改 jenkins 和 sonarqube ，作为内部标准要求所有项目启用。
- 魔改 jenkins 提供的基础 docker 镜像非常有限，无一支持我团队项目的 C++ 运行时；反复沟通后该团队手工添加基础镜像解决，但后继每次镜像升级仍需人工操作。
- 魔改 sonarqube 规则，且不提供开发环境相应工具 /配置 /脚本；只能每次代码提交后等云端执行结果，每次耗时 > 4 minutes ，有时一次功能代码要修改提交三四次才能通过检测。
14
Select Language