样式和格式代码

样式和格式约定使代码看起来一致。

Intuition

阅读代码的频率高于编写代码的频率。——Guido Van Rossum（Python 的作者）

当编写一段代码时，几乎从来都不是最后一次看到它或最后一次编辑它。所以需要解释发生了什么（通过文档）并使其易于阅读。使代码更具可读性的最简单方法之一是遵循一致的样式和格式约定。在遵守 Python 样式约定方面有很多选择，但大多数都基于PEP8约定。不同的团队遵循不同的约定，这完全没问题。最重要的方面是：

• consistency: 每个人都遵循相同的标准。
• automation：在初始配置后，格式化应该很容易。

将使用非常流行的风格和格式约定的混合，代表做出一些非常固执的决定（带有可配置的选项）。

• Black：一个就地重新格式化程序，（大部分）遵守PEP8。
• isort: 对 Python 脚本中的 import 语句进行排序和格式化。
• flake8: 具有符合 PEP8 的风格约定的代码 linter。

安装所需的软件包：

pip install black==22.3.0 flake8==3.9.2 isort==5.10.1

由于这些样式包不是核心机器学习操作的组成部分，让在 中创建一个单独的列表setup.py：

# setup.py
style_packages = [
    "black==22.3.0",
    "flake8==3.9.2",
    "isort==5.10.1"
]

# Define our package
setup(
    ...
    extras_require={
        "dev": docs_packages + style_packages,
        "docs": docs_packages,
    },
)

与 不同docs，不style_packages单独添加，extras_require因为不需要有人只安装样式包。所以可以将它添加到dev选项中。

配置

在可以正确使用这些工具之前，必须配置它们，因为它们之间可能存在一些差异，因为它们遵循从 PEP8 扩展而来的略有不同的约定。

Black

要配置 Black，可以使用CLI 方法传入选项，但通过文件执行此操作效率更高（尤其是这样其他人可以轻松找到所有的配置）。因此，将pyproject.toml在项目目录的根目录中创建一个，内容如下：

touch pyproject.toml

# Black formatting
[tool.black]
line-length = 100
include = '\.pyi?$'
exclude = '''
/(
      .eggs         # exclude a few common directories in the
    | .git          # root of the project
    | .hg
    | .mypy_cache
    | .tox
    | venv
    | _build
    | buck-out
    | build
    | dist
  )/
'''

这里告诉 Black 最大行长度应该是 100 个字符，并且包括和排除某些文件扩展名。

创建 pyproject.toml是为了建立一个更易于阅读的配置文件，该文件旨在替换setup.pyorsetup.cfg文件，并且越来越多地被许多开源库采用。

isort

接下来，将在pyproject.toml文件中配置 isort（就在 Black 的配置下方）：

# iSort
[tool.isort]
profile = "black"
line_length = 79
multi_line_output = 3
include_trailing_comma = true
virtual_env = "venv"

虽然有一个完整的 isort 配置选项列表，但决定明确设置这些选项，这样就不会与 Black 冲突。

flake8

最后，将设置 flake8，但这次需要创建一个单独的.flake8文件来定义其配置：

touch .flake8

[flake8]
exclude = venv
ignore = E501, W503, E226
max-line-length = 79

# E501: Line too long
# W503: Line break occurred before binary operator
# E226: Missing white space around arithmetic operator

在这里，包括一个ignore选项来忽略某些flake8 规则，因此一切都适用于 Black 和 isort 配置。

除了在此处定义全局应用的配置选项外，还可以逐行选择专门忽略某些约定。这是如何利用它的示例：

# tagifai/config.py
import pretty_errors  # NOQA: F401 (imported but unused)

通过将放在一条# NOQA: <error-code>线上，告诉 flake8 不对这 条线上的特定错误进行质量保证。

用法

要使用配置的这些工具，必须从项目目录中执行它们：

black .
flake8
isort .

查看您的文件以了解所做的所有更改！

.表示该包的配置文件在当前目录中

在makefile 课程中，将学习如何将所有这些命令组合成一个。在预提交课程中，将学习如何在更改代码时自动执行此格式化。

---

本文主体源自以下链接：

@article{madewithml,
    author       = {Goku Mohandas},
    title        = { Made With ML },
    howpublished = {\url{https://madewithml.com/}},
    year         = {2022}
}