-
Notifications
You must be signed in to change notification settings - Fork 0
Coding Standards
The current codebase can be used as a guide for formatting conventions. Additional guidelines are provided below. 当前的代码库可以用作格式化约定的指南。下面提供其他指南。
Black is a PEP-8 compliant opinionated formatter and used during the pre-commit step. Black 是一个符合 PEP-8 规范的固执己见的格式化程序，在预提交步骤中使用。
We philosophically agree with the Black formatting style, however it does not currently run over the Cython parts of the codebase. So there you could say we are “handcrafting towards” Black stylistic conventions for consistency. 我们在理念上同意 Black 的格式化风格，但是它目前不运行在代码库的 Cython 部分。所以你可以说我们正在“手工制作”Black 风格的约定以保持一致性。
For longer lines of code, and when passing more than a couple of arguments, you should take a new line which aligns at the next logical indent (rather than attempting a hanging 'vanity' alignment off an opening parenthesis). This practice conserves space to the right, ensures important code is more central in view, and is also robust to function/method name changes. 对于较长的代码行，以及传递多个参数时，您应该换行，并在下一个逻辑缩进处对齐（而不是尝试在左括号后进行悬挂的“虚荣”对齐）。这种做法可以节省右侧的空间，确保重要的代码在视图中更加居中，并且对函数/方法名称更改也具有鲁棒性。
The closing parenthesis should be located on a new line, aligned at the logical indent. 右括号应位于新行，并在逻辑缩进处对齐。
Also ensure multiple hanging parameters or arguments end with a trailing comma: 还要确保多个悬挂参数或参数以尾随逗号结尾：
long_method_with_many_params(
some_arg1,
some_arg2,
some_arg3, # <-- 尾随逗号
)The codebase generally follows the PEP-8 style guide. Even though C typing is taken advantage of in the Cython parts of the codebase, we still aim to be idiomatic of Python where possible. One notable departure is that Python truthiness is not always taken advantage of to check if an argument is None for everything other than collections. 代码库通常遵循 PEP-8 风格指南。即使在代码库的 Cython 部分利用了 C 类型，我们仍然尽可能地使用 Python 的习惯用法。一个值得注意的例外是，除了集合之外，并非总是利用 Python 真值来检查参数是否为 None。
There are two reasons for this; 这有两个原因；
- Cython can generate more efficient C code from is None and is not None, rather than entering the Python runtime to check the PyObject truthiness. Cython 可以从 is None 和 is not None 生成更高效的 C 代码，而不是进入 Python 运行时来检查 PyObject 真值。
- As per the Google Python Style Guide - it’s discouraged to use truthiness to check if an argument is/is not None, when there is a chance an unexpected object could be passed into the function or method which will yield an unexpected truthiness evaluation (which could result in a logical error type bug). 根据 Google Python 风格指南，不建议使用真值来检查参数是否为/不为 None，因为有可能将意外的对象传递到函数或方法中，这将产生意外的真值评估（这可能导致逻辑错误类型错误）。
“Always use if foo is None: (or is not None) to check for a None value. E.g., when testing whether a variable or argument that defaults to None was set to some other value. The other value might be a value that’s false in a boolean context!” 始终使用 if foo is None:（或 is not None）来检查 None 值。例如，在测试默认值为 None 的变量或参数是否设置为其他值时。另一个值可能是在布尔上下文中为假的值！
Having said all of this there are still areas of the codebase which aren’t as performance-critical where it is safe to use Python truthiness to check for None. 话虽如此，代码库中仍然存在一些对性能要求不高的区域，在这些区域中使用 Python 真值来检查 None 是安全的。
note 注意
To be clear, it's still encouraged to use Python truthiness is and not to check if collections are None or empty. 需要说明的是，仍然鼓励使用 Python 真值 is 和 not 来检查集合是否为 None 或为空。
We welcome all feedback on where the codebase departs from PEP-8 for no apparent reason. 我们欢迎对代码库无故偏离 PEP-8 的地方提出任何反馈。
The NumPy docstring spec is used throughout the codebase. This needs to be adhered to consistently to ensure the docs build correctly. 整个代码库都使用 NumPy 文档字符串规范。需要始终遵守这一点，以确保文档构建正确。
Flake8 is utilized to lint the codebase. Current ignores can be found in the top-level pre-commit-config.yaml, with the justifications also commented. Flake8 用于对代码库进行 linting。当前的忽略可以在顶级的 pre-commit-config.yaml 中找到，理由也已注释。
Here are some guidelines for the style of your commit messages: 以下是提交消息风格的一些指南：
- Limit subject titles to 50 characters or fewer. Capitalize subject line and do not end with period. 将主题标题限制为 50 个字符或更少。主题行首字母大写，不要以句号结尾。
- Use 'imperative voice', i.e. the message should describe what the commit will do if applied. 使用“祈使语气”，即消息应描述提交应用后将执行的操作。
Optional: 可选：
- Use the body to explain change. Separate from subject with a blank line. Keep under 80 character width. You can use bullet points. 使用正文解释更改。与主题用空行分隔。保持在 80 个字符宽度以下。您可以使用项目符号。
- Provide # references to relevant issues or tickets. 提供与相关问题或票证的 # 引用。
- Provide any hyperlinks which are informative. 提供任何有用的超链接。