编码风格#

注意

这是从旧的 IPython wiki 直接复制过来的，目前正在开发中。开发指南的这一部分中的许多信息已经过时。

本文档描述了我们的编码风格。编码风格指的是以下内容：

源代码的格式化方式（缩进、空格等）
事物的命名方式（变量、函数、类、模块等）

通用编码约定#

一般来说，我们遵循 Python 官方风格指南 PEP 8 中所描述的标准 Python 风格约定。

其他一般评论：

在一个大文件中，顶级类和函数之间应间隔两行，以便于视觉上区分它们。
使用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 文件时，您可以使用以下模板作为起点，该模板已经为您预先写入了一些常见的内容。