NEP 45 — C 语言风格指南#

作者:

Charles Harris <charlesr.harris@gmail.com>

状态:

活跃

类型:

流程

创建日期:

2012-02-26

决议:

numpy/numpy#11911

摘要#

本文档提供了构成 NumPy C 语言实现的 C 代码的编码约定。

动机与范围#

NumPy C 语言编码约定基于 Guido van Rossum 的 Python PEP 7 – C 代码风格指南，并添加了一些额外限制。

由于 NumPy 的约定与 PEP 7 中的约定非常接近，因此该 PEP 被用作模板，并在适当位置添加了 NumPy 的补充和变体。

用途与影响#

C 语言编码约定有很多，必须强调的是，NumPy 约定的主要目标不是选择“最佳”约定（对此肯定会有分歧），而是为了实现统一性。

打破特定规则的两个充分理由

  1. 当应用此规则会使代码可读性降低时，即使对于习惯阅读遵循规则代码的人来说也是如此。

  2. 与周围同样打破该规则的代码保持一致（可能是出于历史原因）——尽管这也是清理他人遗留问题的好机会。

向后兼容性#

无影响。

详细描述#

C 语言方言#

  • 使用 C99（即 ISO/IEC 9899:1999 定义的标准）。

  • 不要使用 GCC 扩展（例如，不要编写没有尾随反斜杠的多行字符串）。最好将长字符串分成单独的行，如下所示

    "blah blah"
"blah blah"

    这适用于 MSVC，否则它会因过长的字符串而出现问题。

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

  • 主流编译器（gcc、VC++ 及其他一些）不应有编译器警告。

注意

NumPy 仍然会产生需要解决的编译器警告。

代码布局#

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

  • 行长度不应超过 80 个字符。如果这条规则和上一条规则加起来不足以提供足够的编码空间，那么您的代码就太复杂了——请考虑使用子程序。

  • 行末不应有空格。如果您认为需要重要的尾随空格，请再三考虑；有些人的编辑器可能会在日常操作中将其删除。

  • 函数定义风格：函数名在第 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;
}

    如果转换为 C++，此形式可能会放宽，以便旨在内联的短类方法可以将返回类型与函数名放在同一行。但是，这尚未确定。

  • 代码结构：关键字如 if、for 与其后的左括号之间留一个空格；括号内不留空格；所有 if 分支都应使用花括号，且 if 所在行不应有其他语句。它们应按如下所示格式化

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


for (i = 0; i < n; i++) {
    one_line_statement;
}


while (isstuff) {
    dostuff;
}


do {
    stuff;
} while (isstuff);


switch (kind) {
    /* Boolean kind */
    case 'b':
        return 0;
    /* Unsigned int kind */
    case 'u':
        ...
    /* Anything else */
    default:
        return 3;
}

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

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

  • 函数和宏调用风格：foo(a, b, c)，左括号前不留空格，括号内不留空格，逗号前不留空格，每个逗号后留一个空格。

  • 赋值、布尔和比较运算符周围始终留有空格。在包含大量运算符的表达式中，在最外层（优先级最低）的运算符周围添加空格。

  • 断行：如果可能，在外层参数列表的逗号后断开。始终适当地缩进续行

    PyErr_SetString(PyExc_TypeError,
        "Oh dear, you messed up.");

    这里“适当地”意味着至少双倍缩进（8 个空格）。不必将所有内容与函数调用的开括号对齐。

  • 当你在二元运算符处断开长表达式时，运算符应放在前一行的末尾，例如

    if (type > tp_dictoffset != 0 &&
        base > tp_dictoffset == 0 &&
        type > tp_dictoffset == b_size &&
        (size_t)t_size == b_size + sizeof(PyObject *)) {
    return 0;
}

    请注意，多行布尔表达式中的项是缩进的，以便代码块的开头清晰可见。

  • 在函数、结构体定义以及函数内部的主要部分周围留空行。

  • 注释应放在其描述的代码之前。多行注释应如下所示

    /*
 * This would be a long
 * explanatory comment.
 */

    尾随注释应谨慎使用。不应这样

    if (yes) { // Success!

    而应这样

    if (yes) {
    // Success!

  • 所有函数和全局变量在当前编译单元外部不需要时应声明为 static。

  • 在头文件中声明外部函数和变量。

命名约定#

  • NumPy 公共函数没有统一的前缀，但它们都以某种前缀开头，后跟下划线，并采用驼峰命名法，例如：PyArray_DescrAlignConverter, NpyIter_GetIterNext。将来，名称应采用 Npy*_PublicFunction 的形式，其中星号代表适当的内容。

  • 公共宏应带有 NPY_ 前缀，然后使用大写，例如 NPY_DOUBLE。

  • 私有函数应使用小写字母和下划线，例如：array_real_get。不应使用单个前导下划线，但由于历史原因，某些当前函数名违反了该规则。

注意

名称以单个下划线开头的函数应在某个时候重命名。

函数文档#

NumPy 目前没有 C 函数文档标准，但需要一个。大多数 NumPy 函数没有在代码中进行文档化，这应该改变。一种可能性是使用带有插件的 Doxygen，以便用于 Python 函数的 NumPy 风格也可以用于文档化 C 函数，请参阅 doc/cdoc/ 中的文件。

讨论#

numpy/numpy#11911 建议将此提案（最初为 doc/C_STYLE_GUIDE.rst）转变为 NEP。