代码质量管理

1. 背景

代码质量是程序员工作的核心。关注代码质量有以下几个重要原因：

• 提升代码的可读性；
• 提高可维护性；
• 提高程序可持续性水平，减少错误与BUG；
• 促进团队协作：当代码质量统一、规范一致时，团队成员之间的沟通和协作更加容易，减少了因代码风格不一致而引发的冲突和问题；
• 优化性能。

2. 质量管理

在软件开发中，代码质量至关重要，下面介绍几种质量管理的方法。

2.1 建立标准

2.1.1 规范化

建立代码规范与代码审查(Code Review)制度。

代码规范可以通过文档的形式定义（各个语言业界都有开源的规范可以学习），也可根据自身团队的特点和习惯增加一些额外的规范。

开发者根据规范编写代码后，需要另外一个人对新增的代码进行Code Review，对reviewer来说需要具备review的能力，并且清晰知道自己需要审查什么内容，例如：

• 代码实现方案是否合理 （方案应当在编码前沟通确认）
• 命名是否规范
• 单个函数行数是否过多
• 关键性数据库写入操作是否有事务和锁
• （等等）

2.1.2 自动化

无论规范定义的多好，开发者学习的如何，开发者总有疏忽的时候。

应当使用工具自动检查代码质量，原则 能自动化就尽量自动化。

自动化不仅可以保证规范能够如实落地，也能够节省人力。

代码一般通过 git 管理，可以将自动化工具同 git hooks 结合使用。

本地自动化工具推荐 pre-commit。

安装和使用方式官网都有很详细说明，这里仅做简单介绍。

• 安装 pip install pre-commit；mac也可以通过 brew install pre-commit 安装；
• 项目根目录的配置文件 .pre-commit-config.yaml ；
• 像git hooks里增加相关hook pre-commit install --hook-type pre-commit --hook-type commit-msg，这样之后提交代码就会执行相应检查；

这里以Python为例，推荐一份配置：

repos:
-   repo: https://github.com/psf/black-pre-commit-mirror
    rev: 24.4.2
    hooks:
      - id: black
        args: ['--line-length', '120']
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.1.0
    hooks:
    -   id: end-of-file-fixer
    -   id: check-docstring-first
    -   id: check-json
    -   id: check-added-large-files
    -   id: check-yaml
    -   id: debug-statements
    -   id: trailing-whitespace
-   repo: https://github.com/pycqa/flake8
    rev: 3.8.3
    hooks:
    -   id: flake8
        args: ['--max-line-length', '120']
-   repo: https://github.com/pre-commit/mirrors-mypy
    rev: 'v1.9.0'  # Use the sha / tag you want to point at
    hooks:
    -   id: mypy
        args: ['--disallow-untyped-defs', '--ignore-missing-imports']
        additional_dependencies: [tokenize-rt==3.2.0]
        exclude: "tests"
-   repo: https://github.com/pre-commit/pre-commit.git
    rev: v2.6.0
    hooks:
    -   id: validate_manifest
-   repo: https://github.com/commitizen-tools/commitizen
    rev: v2.1.0
    hooks:
      - id: commitizen
        stages: [commit-msg]
        additional_dependencies: [ MarkupSafe==2.0.1 ]

其中每一个repo都对应一个自动化工具。

注意：代码提交后，可以在git上增加 workflow ，在提交PR的时候执行对应的检查工具。

另外，单元测试覆盖度也有相应的工具处理。可以参考 如何选择Python测试框架：pytest和unittest

2.1.3 流程化

将代码质量检查与代码流动过程绑定。

例如： 需求 --> 方案讨论 --> 代码编写 --> PR (必须) --> Code Review --> 测试 --> 上线

开发者将需求分支的代码合并到test/master的时候，必须通过PR(Pull Request)，PR会执行对应的自动化工具，完成自动化的代码检查、测试用例及其覆盖度等。

2.2 Bug归类复盘

对于测试、或者上线后出现的所有问题，都应当记录，用于事后归类分析复盘。

复盘是为了之后如何避免此类问题，需要考虑：

• 是否需要补充规范？
• 是否需要完善流？
• 自动化工具是否能够检测？

2.3 文档管理

良好的文档能够帮助开发者快速理解代码库和项目结构，是长期维护项目的关键资产。高质量的文档应该定期更新，反映最新的代码变更和设计决策。

2.4 团队协作和知识共享

管理者可以通过建立信任环境、提供合适的工具和技术支持、创造共享的目标和价值、奖励和认可团队成员的共享行为以及培养开放和合作的团队文化等方式鼓励这一过程。特别是建立信任环境，这是知识共享的基础。通过增强团队成员之间的信任，项目经理可以促进一个安全的环境，鼓励团队成员分享彼此的知识和经验，从而提高团队的整体协作和效率。

此外，对于重复的代码、通用的功能（例如接口权限管理、操作审计、用户管理等），应该有适度的技术沉淀，考虑是否应当封装成统一函数、甚至封装成一个可以直接安装引用的lib。这样其他服务或者团队就能直接使用，不仅能够节省开发成本和维护成本，还能提升代码质量。

参考

• 代码质量管控的四个阶段
• 缺陷管理规范