PEP 7 – C 代码风格指南

介绍

本文档给出了包含 C 的 C 代码的编码约定 Python 的实现。请参阅配套信息 PEP 描述 Python 代码的样式指南。

请注意，规则是要被打破的。打破 特别规则：

当应用该规则会降低代码的可读性时，即使 习惯于阅读遵循规则的代码的人。

为了与周围的代码保持一致，这些代码也会破坏它（也许 出于历史原因）——尽管这也是一个机会 清理别人的烂摊子（以真正的XP风格）。

C方言

Python 3.11 及更新版本使用没有可选功能的 C11。 公共 C API 应与 C++ 兼容。

Python 3.6 到 3.10 将 C89 与几个选定的 C99 功能结合使用：

和 中的标准整数类型。我们 需要固定宽度的整数类型。<stdint.h><inttypes.h>

static inline功能

指定的初始值设定项（特别适合类型声明）

混合声明

布尔 值

C++ 样式的行注释

3.6 之前的 Python 版本使用 ANSI/ISO 标准 C（1989 年版本 的标准）。这意味着（除其他外）所有 声明必须位于块的顶部（不一定位于 功能顶部）。

不要使用特定于编译器的扩展，例如 GCC 或 MSVC 的扩展 （例如，不要编写没有尾随反斜杠的多行字符串）。

所有函数声明和定义都必须使用完整的原型 （即指定所有参数的类型）。

主要编译器（gcc、VC++、其他一些编译器）没有编译器警告。

static inline函数应优先于新 中的宏 法典。

代码布局

使用 4 空格缩进，完全不使用制表符。

任何行的长度都不应超过 79 个字符。如果 this 和 以前的规则一起不给你足够的空间来编码，你的代码 太复杂了 - 考虑使用子例程。

任何行都不应以空格结尾。如果您认为您需要显着的 尾随空格，再想一想——某人的编辑器可能会删除 这是例行公事。

函数定义样式：函数名称在第 1 列最外层 第 1 列中的大括号，局部变量后的空行 声明。

static int
extra_ivars(PyTypeObject *type, PyTypeObject *base)
{
    int t_size = PyType_BASICSIZE(type);
    int b_size = PyType_BASICSIZE(base);

    assert(t_size >= b_size); /* type smaller than base! */
    ...
    return 1;
}

代码结构：关键字之间有一个空格，如 和 以下左帕伦;paren内没有空间;大括号是 在任何地方都需要，即使 C 允许省略它们，但确实如此 不要将它们添加到您未以其他方式修改的代码中。全新 C 代码需要大括号。大括号的格式应如下所示：iffor

if (mro != NULL) {
    ...}else {
    ...}

return 语句不应使用多余的括号：

return albatross; /* correct */return(albatross); /* incorrect */

函数和宏调用样式： – 前面没有空格 开放的 paren，parens 内没有空格，之前没有空格 逗号，每个逗号后一个空格。foo(a, b, c)

始终在赋值、布尔值和比较周围放置空格 运营商。在使用大量运算符的表达式中，添加空格 围绕最外层（优先级最低）的运算符。

断开长行：如果可以，请在最外层的逗号后断开 参数列表。始终适当地缩进连续行， 例如：

PyErr_Format(PyExc_TypeError,
             "cannot create '%.100s' instances",
             type->tp_name);

当您在二进制运算符处断开长表达式时， 运算符位于上一行的末尾，大括号应为 格式如图所示。例如：

if (type->tp_dictoffset != 0 && base->tp_dictoffset == 0 &&
    type->tp_dictoffset == b_size &&
    (size_t)t_size == b_size + sizeof(PyObject *)){
    return 0; /* "Forgive" adding a __dict__ only */}

垂直对齐多行宏中的行延续字符。

打算用作语句的宏应使用宏习语， 没有最后的分号。 例：do { ... } while (0)

#define ADD_INT_MACRO(MOD, INT)                                   \
    do {                                                          \        if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) {  \
            goto error;                                           \        }                                                         \    } while (0)// To be used like a statement with a semicolon:ADD_INT_MACRO(m, SOME_CONSTANT);

#undef使用后归档本地宏。

在函数、结构定义和主要内容周围放置空行 函数内的部分。

注释位于它们所描述的代码之前。

所有函数和全局变量都应声明为静态，除非 它们将成为已发布界面的一部分

对于外部函数和变量，我们总是有一个声明 在“Include”目录中的相应头文件中，该文件使用 宏和宏，如下所示：PyAPI_FUNC()PyAPI_DATA()

PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);PyAPI_DATA(PyTypeObject) PySuper_Type;

命名约定

为公共功能使用前缀;从不静态 功能。前缀是为全局服务保留的 例程喜欢 ;特定例程组 （例如，特定对象类型 API）使用更长的前缀， 例如： 用于字符串函数。PyPy_Py_FatalErrorPyString_

公共函数和变量使用带有下划线的 MixedCase，例如 这：。PyObject_GetAttrPy_BuildValuePyExc_TypeError

有时，加载器必须看到“内部”功能; 我们为此使用前缀，例如：._Py_PyObject_Dump

宏应具有 MixedCase 前缀，然后使用大写字母，用于 例：。PyString_AS_STRINGPy_PRINT_RAW

宏参数应使用样式， 因此，它们很容易与 C 变量和结构体成员区分开来。ALL_CAPS

文档字符串

将 or 宏用于文档字符串 支持在没有文档字符串的情况下构建 Python（）。PyDoc_STR()PyDoc_STRVAR()./configure --without-doc-strings

对于需要支持早于 2.3 的 Python 版本的 C 代码， 您可以在包括以下内容后包括此内容：Python.h

#ifndef PyDoc_STR#define PyDoc_VAR(name)         static char name[]#define PyDoc_STR(str)          (str)#define PyDoc_STRVAR(name, str) PyDoc_VAR(name) = PyDoc_STR(str)#endif

每个函数文档字符串的第一行应该是“签名” line“，它给出了参数和返回值的简要概述。 例如：

PyDoc_STRVAR(myfunction__doc__,"myfunction(name, value) -> bool\n\n\Determine whether name and value make a valid pAIr.");

始终在签名行和文本之间包含空行 的描述。

如果函数的返回值始终为 None（因为有 没有有意义的返回值），不包括 返回类型。

在编写多行文档字符串时，请务必始终使用反斜杠 延续，如上例所示，或字符串文字 串联：

PyDoc_STRVAR(myfunction__doc__,"myfunction(name, value) -> bool\n\n""Determine whether name and value make a valid pair.");

尽管某些 C 编译器接受字符串文本，但两者都没有：

/* BAD -- don't do this! */PyDoc_STRVAR(myfunction__doc__,"myfunction(name, value) -> bool\n\nDetermine whether name and value make a valid pair.");

并非所有人都这样做;众所周知，MSVC 编译器会抱怨这一点。

版权

本文档已置于公有领域。

The End