【Python】代码风格约定_摘自开源项目FreeCAD

以下内容全部摘自开源项目 FreeCAD 的【src\Mod\Draft\coding_conventions.md】文件。
其内容主要是对Python语言中的import 用法、类名、方法名、变量名的简要约定。供参考。

通用

• 所有的文件应在开始放置许可（License）。
• 应使用 Unix 风格的行尾结束符。
• 在同一个文件中不要混用行尾结束符。
• 单层缩进使用4个空格。不要使用 Tab。
• 删除行尾/末尾的空格。
• 文件保持1000行以内。
  • 将较大模块拆分为更小的模块，需要的话可以放入程序包（存放各种模块的子目录）中。
  • 较大函数拆分为较小函数。
  • 较大的类拆分为较小的类，这样一个类可以继承其他类，方便继承他们的方法。

Python

代码格式

• 通常，代码应遵循 PEP 8 和 PEPper 257 约定。
• 每行不超过80个字符。
  • 待翻。
  • 如果出现3层缩进，这说明代码需要重构（refactor）。
• 字符串用双引号 “字符串”

模块和包的导入

• Imports 语句应在文件的开头处，在许可声明和模块docstring说明的后面，
  并且imports 语句应按下面三种类型的顺序组织：
  标准库
  第三方库
  FreeCAD特定库
• import语句应一行一个模块。
• 不用使用带星号 * 的 import 语句，比如 from module import * ，因为这样很难确认被导入的函数和类。
• 不要在 函数或类的内部使用 import 导入模块。

【待翻译】

General

• All files should have the license header at the beginning.
• Unix line endings should be used.
• Never use mixed line endings in the same file.
• Use 4 spaces for a single level of indentation. Do not use tabs.
• Remove trailing white spaces.
• Keep files at less than 1000 lines in size.
  • Break a module into smaller modules, or into a package
    (a subdirectory with various modules),
    as necessary.
  • A big function can be broken into smaller functions.
  • A big class can be broken into smaller classes.
    Then one class can subclass the other ones
    in order to inherit their methods.

Python

Code formatting

• In general, code should follow PEP 8
  and PEP 257 (docstrings).
• Maximum line length should be 80 characters.
  • Find ways to reduce nested blocks of code by using auxiliary variables,
    and functions that encapsulate the operations inside these blocks.
  • If you have more than 3 levels of indentation, this is a sign
    that the code should be refactored.
• Use double quotes for "strings".

Imports

• Imports should be at the beginning of the file,
  after the license header and module docstring,
  and they should be grouped in three types in order:
  standard library imports, third party imports,
  and then FreeCAD specific imports.
• Import only one module per line.
• Do not use asterisk imports, from module import *, as this
  makes it hard to validate imported functions and classes.
• Do not import modules inside a function or class.
• The import of modules that require the graphical interface,
  such as FreeCADGui, should be guarded by an if FreeCAD.GuiUp: test.
• In general, the code should be structured in such a way
  that console-only functions are separate from their graphical interface
  implementations (GuiCommands).

Naming policy

• Follow PEP 8.
• snake_case_names.py for modules.
• variable_names_without_capitals for variables.
• CamelCaseClass for classes.
• CONSTANTS_USE_CAPITALS for constants.
• functions_without_capitals() for functions and class methods.
• Functions expected to return a value should indicate what is expected,
  so is_mesh_valid is a good name, but check_mesh is not a good name.
• Class names, method names, and variables that are auxiliary,
  and not meant to be part of the public interface should start
  with an underscore like _MyInternalClass or _my_small_variable.

Python code formatting tools

• Using a code editor that automatically checks compliance with PEP 8
  is recommended.
• For example, Spyder
  contains code checkers pylint, pyflakes, pycodestyle, jedi,
  sphinx, etc., that automatically test the code as you write it,
  and can provide documentation and hints on the used functions and classes
  in real time, even the ones that you have just written.
• Compliance should be manually checked with flake8.

flake8 --ignore=E226,E266,W503 file.py
1

We may ignore certain errors and warnings.

• E226: spaces around arithmetic operators *, /, +, -;
  sometimes we don’t need a space.
• E266: only one # for comments; we need two ## for Doxygen documentation.
• W503: break lines before a binary operator like and and or.
  The W503 warning will be changed in the future so we can ignore it for now.
• See the meaning of the error codes in the
  pycodestyle documentation.

A good way to test entire folders for compliance is to run
the following command.

find src/Mod/Draft -name '*.py' ! -name InitGui.py -exec flake8 --ignore=E226,E266,W503 --max-line-length=100 '{}' '+'
1

• The online LGTM service
  is also able to analyze the code and detect problems.
• Avoid automatic code formatters.