提交python代码到仓库前，一定要做这3件事

Posted 2023-02-04 刘炫320

1. 前言

话说，一个程序员成长最快的时候，就是在看别人代码的时候，不仅可以帮别人看出错误，也能够从优秀的代码中获得成长。

今天，我要说的是提交python代码到仓库前，一定要做这3件事。他们能够帮助大家规范代码，在提交到github上的时候更加清晰和易维护。

2. 提交代码前需要做的三件事

当我们提交代码到github上的时候，建议做以下三件事：

isort my_code.py
black my_code.py
flake8 my_code.py

my_code.py可以是一个文件，也可以是一个目录。

当你使用以下命令安装后，你就可以使用他们了：

安装black: pip install black
安装isort: pip install isort
安装flake8: pip install flake8

你先不用问这些是干什么的，先运行完，再看一下自己的代码。
然后回过来，再看接下来的内容，听懂掌声。

3. 他们三剑客都是谁？

black是一个自动代码格式化工具，使用黑白名单技术，以简单、快速且一致的方式格式化Python代码。它是完全不可交互的，因此没有用户可以调整的设置，只有一个强制执行的格式规则。
isort是一个Python的import排序工具，用于管理代码中的import语句，使其更加整洁和规范。
支持多种import格式，包括按照模块名称、按照标准库、第三方库、应用程序代码排序。
可以根据用户的需求进行自定义配置，以满足特定项目的需求。
flake8是一个Python的代码检查工具，用于检查代码中的错误、不规范和不一致的地方。
包含了很多不同的检查规则，如代码风格（PEP8）、变量命名、代码复杂度等。
可以通过配置文件对检查规则进行自定义配置，以满足特定项目的需求。

下面是对于三者自定义使用的一些小提示，当然，不设置这些采用默认配置也是可以实现的。

3.1 关于black

black可以在项目根目录下创建 pyproject.toml 文件并设置相应的配置来实现。

[tool.black]
line-length = 88
target-version = ['py37']
include = '\\.pyi?$'
exclude = '''
/(
    \\.git
  | \\.hg
  | \\.mypy_cache
  | \\.tox
  | \\.venv
  | _build
  | buck-out
  | build
  | dist
)/
'''
skip-string-normalization = true

其中：

line-length 设置代码行的最大长度，默认为 88 个字符。

target-version 设置目标 Python 版本，默认为当前环境的 Python 版本。

include 设置需要格式化的文件类型，默认为 ‘.pyi?$’，表示仅格式化 .py 和 .pyi 类型的文件。

exclude 设置需要排除的文件夹，默认为空，即不排除任何文件夹。

skip-string-normalization 是否跳过字符串格式化，默认为 false，即进行字符串格式化。

3.2 关于isort

isort可以在项目根目录下创建.isort.cfg并设置相应的配置来实现。

[settings]
multi_line_output=3
include_trailing_comma=True
force_grid_wrap=0
combine_as_imports=True
line_length=100

其中：
multi_line_output: 导入语句的多行输出格式。
include_trailing_comma: 是否在导入语句的最后加上逗号。
force_grid_wrap: 导入语句是否换行。
combine_as_imports: 是否将相同的导入语句合并在一起。
line_length: 每行最多字符数。

3.3关于flake8

flake8也可以在项目根目录下创建.flake8并设置相应的配置来实现。

[flake8]
ignore = E226,E302,E41
max-line-length = 100
exclude = tests/*

其中：

ignore: 指定忽略的规则，以逗号分隔的代码规则的数字。
max-line-length: 指定行的最大长度。
exclude: 排除检查的目录或文件。

flake8的报告可以显示以下几种类型的问题：

Syntax error：语法错误。
PEP 8 style violations：PEP 8风格违反。
Code complexity issues：代码复杂度问题。
Other error messages, such as undefined variable：其他错误信息，例如未定义变量。
报告包括文件名、行号、代码片段、问题类型以及描述问题的短消息。
下面是一个例子：

$ flake8 myfile.py
myfile.py:7:1: E302 expected 2 blank lines, found 1
myfile.py:11:5: W291 trailing whitespace
myfile.py:13:80: E501 line too long (80 > 79 characters)

其中，错误编码为 E302、W291 和 E501，分别代表预期两个空行但只有一个、存在尾随空格、行过长的错误。在文件 myfile.py 中，第 7 行、第 11 行、第 13 行有这三种错误。

4. 还有其他的一些工具吗？

还有一些其他的代码质量检查工具，如：

• PyLint：静态代码分析工具，可以检查代码的结构、命名规范、代码级别的规范等。
• mypy：静态类型检查工具，可以在代码编写过程中发现类型错误。
• bandit：漏洞检查工具，可以扫描代码并发现潜在的安全风险。

后期还可以使用一些注释自动生成文档的工具，如：

• Doxygen: 是一种文档生成工具，专门为C++, C, Java, Python, IDL等语言生成API文档。它通过解析代码中的注释和其他相关元数据，生成文档，帮助开发者快速了解项目代码。

• Sphinx: 是一个开源的文档生成工具，专门用于生成高质量的文档，并适用于各种语言，特别是Python。它提供了强大的插件体系，可以生成文档，图表，代码访问，和搜索等。

5. 参考文献

black:

官方网站：https://github.com/psf/black
指南：https://black.readthedocs.io/en/stable/
isort:

官方网站：https://github.com/timothycrosley/isort
指南：https://github.com/timothycrosley/isort/blob/main/docs/docs/isort.rst
flake8:

官方网站：https://github.com/PyCQA/flake8
指南：https://flake8.pycqa.org/en/latest/

6. 题外话

以后写代码的流程应该是这样：

1. 我有一个想法
2. ChatGPT来帮我完善一下
3. 我和ChatGPT互相review代码，并增加相应的注释（这块好像只有chatGPT做的比较好。）
4. 用自动化代码检查工具三剑客检查代码
5. 用注释自动生成文档工具生成文档
6. 提交到仓库中。

我一直认为，专业的事情就该交给专业人做，chatGPT是很强，但是也很贵。