@kpatrick 2022-07-05T20:32:17.000000Z 字数 5575 阅读 140

高质量 Python 代码编写和协作开发

Git 产险

1. Python 编码指南

代码格式，PEP指南：

编码规范：PEP 8 – Style Guide for Python Code
Doc string：PEP 257 – Docstring Conventions
TypeHint：PEP 484 – Type Hints

2. 编码规范

2.1 Python 之禅

PEP 20 – The Zen of Python

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than right now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

2.2 常见问题

2.2.1 命名约定

Python 库的命名约定有点混乱，不可能完全一致。但依然有些普遍推荐的命名规范的。新的模块和包 (包括第三方的框架) 应该遵循这些标准。对不同风格的已有的库，建议保持内部的一致性。

如今代码库中有多种命名风格：

lowercase (小写串)
lower_case_with_underscores (带下划线的小写)
UPPERCASE (大写串)
UPPER_CASE_WITH_UNDERSCORES (带下划线的大写串)
CapitalizedWords (首字母大写的单词串或驼峰缩写）
注意: 使用大写缩写时，缩写使用大写字母更好。故 HTTPServerError 比 HttpServerError 更好。
mixedCase (混合大小写，第一个单词是小写)
Capitalized_Words_With_Underscores（带下划线，首字母大写）

有下划线的情况:

_single_leading_underscore (单前置下划线): 弱内部使用标志。例如 from M import 不会导入以下划线开头的对象。
single_trailing_underscore_ (单后置下划线): 用于避免与 Python 关键词的冲突。例如：
Tkinter.Toplevel(master, class_='ClassName')
__double_leading_underscore (双前置下划线): 当用于命名类属性，会触发名字重整。 (在类 FooBar 中，__boo 变成 _FooBar__boo)。
double_leading_and_trailing_underscore(双前后下划线)：用户名字空间的魔法对象或属性。例如 __init__ , __import__ or __file__，不要自己发明这样的名字。

2.2.2 缩进

YES

# 对准左括号
foo = long_function_name(var_one, var_two,
                         var_three, var_four)
# 不对准左括号，但加多一层缩进，以和后面内容区别。
def long_function_name(
        var_one, var_two, var_three,
        var_four):
    print(var_one)
# 悬挂缩进必须加多一层缩进.
foo = long_function_name(
    var_one, var_two,
    var_three, var_four)

# 不使用垂直对齐时，第一行不能有参数。
foo = long_function_name(var_one, var_two,
    var_three, var_four)
# 参数的缩进和后续内容缩进不能区别。
def long_function_name(
    var_one, var_two, var_three,
    var_four):
    print(var_one)

2.2.3 空行

两行空行分割顶层函数和类的定义。
类的方法定义用单个空行分割。
额外的空行可以必要的时候用于分割不同的函数组，但是要尽量节约使用。
额外的空行可以必要的时候在函数中用于分割不同的逻辑块，但是要尽量节约使用。

YES

def add(a: int, b: int) -> int:
    return a + b
def sub(a: int, b: int) -> int:
    return a - b

class Calculator:
    def __init__(self):
        pass
    def add(self, a: int, b: int) -> int:
        return a + b
    def sub(self, a: int, b: int) -> int:
        return a - b

2.2.4 全局变量

变量尽量只用于模块内部，约定类似函数。

对设计为通过 from M import 来使用的模块，应采用 __all__ 机制来防止导入全局变量；或者为全局变量加一个前置下划线。

2.2.5 Docstring

2.2.6 TypeHint

......

3. 用辅助工具完成高质量代码编写

3.1 Git hooks

Git能在特定的重要动作发生时触发自定义脚本钩子。钩子分为两组：
- 客户端钩子：pre-commit, prepare-commit-msg, commit-msg, post-commit 等，主要在服务端接收提交对象时、推送到服务器之前调用。
- 服务器钩子：pre-receive, post-receive, update 等，主要在服务端接收提交对象时、推送到服务器之前调用。

3.2 pre-commit

pre-commit：是 git hooks 中的一个钩子，由 git commit 命令调用，可以通过 --no-verify 参数绕过调用 pre-commit。通常用于在提交代码前，进行代码规范检查。

但是如果直接通过编写 git hooks 脚本来实现代码规范检查，会有如下的一些问题：

规范越多，编写的脚本越复杂
本地的规范修改，没法方便的同步到项目中其他开发人员
不同语言，代码规范不一样，脚本设置都不同

为了更方便的管理 pre-commit 的设置，于是有了一个同名的工具项目 pre-commit，一个用于管理和维护多语言预提交挂钩的框架。官网地址：https://pre-commit.com/

3.3 使用步骤

安装：pip install pre-commit
设置配置文件：pre-commit 依赖项目根目录配置文件 .pre-commit-config.yaml，需要手动在根目录创建此文件。
设置 git hooks 脚本：pre-commit install
对所有文件进行一次检查(可选)：pre-commit run --all-files

3.4 个人配置推荐

根据个人开发经验，提交代码前完成对基础格式、文档、import 和 type hint 等方面进行检查，推荐的插件有以下 6 个：

pre-commit-hooks —— 检查基础的格式，包括文件末尾是否有空行，是否有额外空格等
black —— 基于 PEP 8，检查基础的编码规范，自动修正代码格式。
isort —— 基于 PEP 8，检查 import 顺序，并自动调整
autoflake8 —— 基于 PEP 8，检查是否存在无用的 import，并自动删除
pydocstyle —— 基于 PEP 257，检查代码中函数和类的 Docstring 是否欠缺，是否符合要求。
mypy —— 基于 PEP 474，检查 Type Hint 的格式。

通过此配置可以完成上述 6 个插件的安装（通过例子进行演示）：.pre-commit-config.yaml

  - repo: https://github.com/pre-commit/pre-commit-hooks.git
    rev: v4.3.0
    hooks:
      - id: check-merge-conflict
      - id: check-symlinks
      - id: end-of-file-fixer
      - id: trailing-whitespace
  - repo: https://github.com/fsouza/autoflake8
    rev: v0.3.2
    hooks:
      - id: autoflake8
  - repo: https://github.com/psf/black
    rev: 22.6.0
    hooks:
      - id: black
  - repo: https://github.com/pycqa/pydocstyle
    rev: 6.1.1
    hooks:
      - id: pydocstyle
        args: [--convention, google, --add-ignore, D100]
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.961
    hooks:
      - id: mypy
        args: [--disallow-untyped-defs, --ignore-missing-imports]
  - repo: https://github.com/pycqa/isort
    rev: 5.10.1
    hooks:
      - id: isort

4. 代码协作流程

4.1 分支策略

当前基于 Git 的分支策略主要有 Gitflow、GitHub flow、GitLab flow 三个派别。如果无需执行严格的版本计划和保证定期发布相关需求的特性，一般可以采取最简便的GitHub flow。

GitHub flow 推荐的策略可以分成以下6步：

Create a branch：在自己的本地仓库中，拉取最新的 Master 分支，并创建一个用于开发新特性/修复问题的 Feature 分支。
Make changes：修改代码，并完成自测，pre-commit 检查和修复代码风格、格式和注释等问题。完成后将 Feature 提交至个人远程仓库。
Create a pull request：提交一个 Pull Request/Merge Request，将个人远程仓库的 Feature 分支的 commits 请求合入 Master。
Address review comments：管理员完成对 PR 的 Code Review，针对代码修改处的设计、规范、功能等进行逐一严格审查，审查不通过时要求开发者进行修改。此过程中还可能会有存在代码冲突、CI 等问题，可能会有多次循环。
Merge your pull request：完成 Code Review 后，管理员将代码 Merge 进到 Master 分支。
Delete your branch：可选步骤，开发者可以删除个人远程和本地的 Feature 分支。

4.2 Merge or Rebase

一般而言，当我们需要从一个分支获取信息，并且合并到当前分支时，我们可以采用 Rebase 或者 Merge 的操作。如图所示：你在一个 Feature 分支进行新特性的开发，与此同时，master 分支的也有新的提交。

4.2.1 Merge（推荐）

git merge master feature

Merge 特点：

自动创建一个新的 commit，如果合并的时候遇到冲突，仅需要修改后重新 commit
优点：记录了真实的 commit 情况，包括每个分支的详情
缺点：每次自动产生一个 merge commit，所以在使用 git log --graph 或者 GUI 工具时，如果 commit 比较频繁，看到分支很杂乱。

4.2.2 Rebase（慎用）

git checkout feature
git rebase master

Rebase 特点：

合并之前的 commit 历史
优点：得到更简洁的项目历史，去掉了 Merge commit
缺点：如果合并出现代码问题不容易定位，因为修改了历史

Rebase 冲突：
合并时如果出现冲突需要按照如下步骤解决

修改冲突部分的代码，并通过 git add 标记已解决
git rebase --continue

注意，不能在公共分支上执行 Rebase ！Rebase 后不仅历史发生改变，所有开发者都受其影响。

4.3 Code Reivew

从观念上，要把 Code Review 置于与代码开发和测试同等重要的地位。具体要做到以下几点：

对所有检查的代码逻辑要做到 完全看懂，对于审核的代码，熟悉程度要做到 如数家珍。如果在审核代码后，对代码的逻辑和背后的原因仍然很模糊，则是一个失败的 Code Review。
好代码的标准，不仅仅是 可以运行通过，在正确性、可读性、可重用性、可运维性等方面上，都需要综合考虑。
建立 Code Review 和写代码一样重要的意识。即：
- Code Review 和写代码一样，也有产出，即产出更高质量的代码。
- 审核代码在很多情况下比写代码还要辛苦，需要理解和找出问题等。
以提升代码质量为最终目标。
要投入足够的时间和精力：
- 要有时间意识。审核代码花费的时间经常和写代码一样多，有时甚至比写代码的时间更多。
- 要有责任意识。如果出现 Bug，不仅仅是写代码人员的职责，也不仅仅是 QA 的职责，代码审核者也需要承担相当大的责任。