编码风格#

注意

这完全复制自旧的 IPython wiki，目前正在开发中。本开发指南的许多信息已过时。

本文档描述了我们的编码风格。编码风格指的是以下几点

  • 源代码的格式（缩进、空格等）

  • 事物的命名（变量、函数、类、模块等）

通用编码约定#

通常，我们遵循 Python 官方风格指南 PEP 8 中描述的标准 Python 风格约定。

其他一般注释

  • 在一个大文件中，顶层类和函数之间应该用 2 行分隔，以便于视觉上区分它们。

  • 使用 4 个空格进行缩进，绝不使用硬制表符。

  • 在具有相同方法的类中保持方法的顺序一致。这对于实现相似接口的类和相似的接口尤其如此。

命名约定#

对于命名约定，我们也遵循 PEP 8 的指导原则。一些现有代码未能完全遵循此原则，但对于所有新的和重构的 IPython 代码，我们将使用

  • 所有 小写 模块名。长模块名可以使用下划线分隔单词（really_long_module_name.py），但这不是必需的。尝试使用附近文件的约定。

  • 类名使用 驼峰命名法（CamelCase）。

  • 方法、函数、变量和属性使用 下划线分隔小写字母（lowercase_with_underscores）。

  • 特定于实现的私有方法将使用 _单下划线前缀（_single_underscore_prefix）。带有双下划线前缀的名称只在特殊情况下使用，因为它们会使子类化变得困难（子类不易看到此类名称）。

  • 偶尔会使用一些连字符小写名称，但主要用于非常短的名称，或者当我们实现的方​​法与基类中现有方法非常相似时（例如 runlines()，其中 runsource() 和 runcode() 已经建立了先例）。

  • 旧的 IPython 代码库中，类和模块名称混杂着显式的 IP 或 ip 前缀。这并非必需，所有新代码都不应使用此前缀。只有当类或函数预期要导入到外部命名空间中，并且其通用名称（如 Shell）可能与其他名称冲突时，这种方法才合理。但是，如果前缀似乎绝对必要，则更倾向于使用更具体的 IPY 或 ipy。

  • 所有 JavaScript 代码也应遵循这些命名约定。

对象属性声明#

通常，对象应该在它们的类中声明对象在其整个生命周期中将持有的所有属性。虽然 Python 允许您在任何时间点向实例添加属性，但这使得代码更难阅读，并且要求方法不断使用 hasattr() 检查或 try/except 调用。通过在类头中声明对象的所有属性，可以有一个地方来理解对象的数据接口，注释可以解释每个变量的作用，并且在可能的情况下，可以分配合理的默认值。

如果一个属性旨在包含一个可变对象，它应该在类中设置为 None，并且其可变值应该在对象的构造函数中设置。由于类属性由所有实例共享，未能做到这一点可能会导致难以跟踪的错误。但是您仍然应该在类声明中设置它，以便接口规范是完整的并在一个地方进行文档化。

一个简单的例子

class Foo(object):
    # X does..., sensible default given:
    x = 1
    # y does..., default will be set by constructor
    y = None
    # z starts as an empty list, must be set in constructor
    z = None

    def __init__(self, y):
        self.y = y
        self.z = []

新文件#

当为 IPython 启动一个新的 Python 文件时，您可以使用 以下模板 作为起点，其中已经为您预写了一些常用内容。