PEP 7 – C 代码风格指南

猫勺猫勺 02-20 233 阅读 0 评论

介绍

本文档给出了包含 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 微信扫一扫

文章声明:以上内容(如有图片或视频在内)除非注明,否则均为腾龙猫勺儿原创文章,转载或复制请以超链接形式并注明出处。

本文作者:猫勺本文链接:https://www.jo6.cn/post/11.html

上一篇 下一篇

相关阅读

发表评论

访客 访客
快捷回复: 表情:
评论列表 (暂无评论,233人围观)

还没有评论,来说两句吧...

取消
微信二维码
微信二维码
支付宝二维码