c++编码规范_Python02编码规范

俗话说无规范不方圆

官网

https://www.python.org/dev/peps/pep-0008/

前言

Guido的主要见解之一是代码被读取的次数多于其编写的次数。此处提供的指南旨在提高代码的可读性，并使其在各种Python代码中保持一致。正如PEP 20所说，“可读性至关重要”。

代码布局

缩进

每个缩进级别使用4个空格。

续行应该使用在括号，方括号和花括号内使用Python的隐式线垂直对齐包装的元素，或使用悬挂式缩进 [7]。使用悬挂式凹痕时，应考虑以下几点：第一行不应包含任何参数，并且应使用进一步的缩进形式将其清楚地区分为延续行：

最大线长限制

所有行最多79个字符。

为了使较长的文本块具有较少的结构限制(文档字符串或注释)，行长应限制为72个字符。

空行

用两个空行包围顶级函数和类定义。

类内的方法定义由单个空白行包围。

多余的空白行可以(分别)用于分隔相关功能组。一堆相关的单线(例如，一组虚拟实现)之间可以省略空白行。

在函数中使用空白行，以节省空间，以指示逻辑部分。

源文件编码

核心Python发行版中的代码应始终使用UTF-8(或Python 2中的ASCII)。

使用ASCII(在Python 2中)或UTF-8(在Python 3中)的文件不应具有编码声明。

导入

1、导入通常应在单独的行上：

2、导入总是放在文件的顶部，紧随任何模块注释和文档字符串之后，以及模块全局变量和常量之前。

导入应按以下顺序分组：

标准库导入。

相关第三方进口。

本地应用程序/库特定的导入。

您应该在每组导入之间放置一个空白行。

3、推荐绝对导入，因为如果导入系统配置不正确(例如，程序包中的目录最终位于sys.path时)，则它们通常更具可读性，并且通常表现更好(或至少会提供更好的错误消息)：

4、从包含类的模块中导入类时，通常可以这样拼写：

5、应该避免使用通配符导入(来自 import *)，因为通配符使不清楚名称空间中存在哪些名称，从而使阅读器和许多自动化工具都感到困惑。

模块级Dunder名称

模块级“dunders”(即名称具有两个前缘和两个纵下划线)如__all__，__author__，__version__等应被放置在模块文档字符串之后，但在任何导入语句以外从__future__进口。Python强制要求将来导入必须在模块中出现在除文档字符串以外的任何其他代码之前：

字符串引号

在Python中，单引号字符串和双引号字符串是相同的。本PEP对此不做任何建议。选择一条规则并坚持下去。但是，当字符串包含单引号或双引号字符时，请使用另一个以避免在字符串中使用反斜杠。它提高了可读性。

对于三引号字符串，请始终使用双引号字符以与PEP 257中的docstring约定一致。

表达式和语句中的空格

在以下情况下，请避免使用多余的空格：

注释

与代码矛盾的注释比没有注释更糟糕。当代码更改时，始终要始终使注释保持最新状态！

评论应为完整句子。第一个单词应大写，除非它是一个以小写字母开头的标识符(请勿更改标识符的大小写！)。

整体注释通常由一个或多个完整句子组成的段落组成，每个句子以句点结尾。

在多句注释中，除了最后一个句子之外，您应该在句子结尾句后使用两个空格。

确保您的注释清晰明了，并且其他母语使用者也很容易理解。

来自非英语国家的Python编码人员：请用英语写您的评论，除非您有120％的把握确保不会说这种语言的人不会阅读该代码。

文档字符串

在PEP 257中，编写好的文档字符串(也称为“文档字符串”)的约定不朽。

为所有公共模块，函数，类和方法编写文档字符串。对于非公共方法，文档字符串不是必需的，但是您应该具有描述该方法功能的注释。该注释应出现在def行之后。

命名约定

Python库的命名约定有点混乱，因此我们永远都无法做到完全一致-尽管如此，这是当前推荐的命名标准。新的模块和软件包(包括第三方框架)应按照这些标准编写，但是如果现有库具有不同的样式，则首选内部一致性。

首要原则

对于用户而言，作为API公共部分可见的名称应遵循反映用法而不是实现的约定。

描述性：命名样式

有很多不同的命名样式。能够独立于它们的用途来识别正在使用的命名样式。

通常区分以下命名样式：

b(单个小写字母)

B(单个大写字母)

小写

lower_case_with_underscores

大写

UPPER_CASE_WITH_UNDERSCORES

大写的单词(或CapWords或CamelCase-之所以命名，是因为其字母的颠簸外观[4])。有时也称为StudlyCaps。

注意：在CapWords中使用首字母缩写词时，请使用首字母缩写词的所有字母大写。因此，HTTPServerError比HttpServerError好。

mixedCase(与大小写字母首字母小写字母不同！)

Capitalized_Words_With_Underscores(难看！)

还有一种使用短的唯一前缀将相关名称组合在一起的样式。这在Python中使用不多，但是为了完整起见提到它。例如，os.stat()函数返回一个元组，该元组的项目传统上具有诸如st_mode，st_size，st_mtime等名称。(这样做是为了强调与POSIX系统调用结构的字段的对应关系，这有助于程序员熟悉该结构。)

软件包和模块名称

模块应使用简短的全小写名称。如果模块名称可以提高可读性，则可以在模块名称中使用下划线。尽管不鼓励使用下划线，但Python软件包也应使用短小写全名。

当用C或C ++编写的扩展模块具有随附的Python模块提供更高级别(例如，更多面向对象)的接口时，C / C ++模块具有下划线(例如_socket)。

类名

类名通常应使用CapWords约定。

在接口被记录并主要用作可调用函数的情况下，可以代替使用函数的命名约定。

请注意，内置名称有一个单独的约定：大多数内置名称是单个单词(或两个单词一起运行)，而CapWords约定仅用于异常名称和内置常量。

类型变量名

在PEP 484中引入的类型变量的名称通常应使用CapWords，而应使用短名称：T，AnyStr，Num。建议将后缀_co或_contra添加到用于分别声明协变或反变行为的变量中：

异常名称

因为异常应该是类，所以在这里适用类命名约定。但是，您应该在异常名称上使用后缀“ Error”(如果异常实际上是一个错误)。

全局变量名

(我们希望这些变量只能在一个模块内使用。)这些约定与函数的约定大致相同。

设计用于通过M import *使用的模块应使用__all__机制以防止导出全局变量，或使用较早的约定在此类全局变量前加下划线(您可能需要这样做以表明这些全局变量是“非公共模块” ”)。

函数和变量名

函数名称应小写，必要时用下划线分隔单词以提高可读性。

变量名与函数名遵循相同的约定。

仅在已经是主流样式(例如threading.py)的上下文中才允许使用mixedCase，以保持向后兼容性。

函数和方法参数

始终将self作为实例方法的第一个参数。

始终对类方法的第一个参数使用cls。

如果函数参数的名称与保留关键字发生冲突，通常最好在末尾附加一个下划线，而不要使用缩写或拼写错误。因此，class_优于clss。(也许最好通过使用同义词来避免此类冲突。)

方法名称和实例变量

使用函数命名规则：小写字母，必要时用下划线分隔单词，以提高可读性。

仅对非公共方法和实例变量使用一个前划线。

为避免名称与子类冲突，请使用两个前导下划线来调用Python的名称处理规则。

Python用类名来修饰这些名称：如果类Foo具有名为__a的属性，则Foo .__ a不能访问它。(坚持的用户仍然可以通过调用Foo._Foo__a来获得访问权限。)通常，双引号下划线仅应用于避免名称与设计为子类的类中的属性发生冲突。

注意：关于__name的使用存在一些争议(请参见下文)。

常数

常量通常在模块级别定义，并以所有大写字母书写，并用下划线分隔单词。示例包括MAX_OVERFLOW和TOTAL。