PEP: 7
Title: Style Guide for C Code
Author: Guido van Rossum <[email protected]>, Barry Warsaw <[email protected]>
Status: Active
Type: Process
Created: 05-Jul-2001
Post-History:

. highlight:: c

Introduction
============

This document gives coding conventions for the C code comprising the C
implementation of Python.  Please see the companion informational PEP
describing :pep:`style guidelines for Python code <8>`.

Note, rules are there to be broken.  Two good reasons to break a
particular rule:

1. When applying the rule would make the code less readable, even for
  someone who is used to reading code that follows the rules.

2. To be consistent with surrounding code that also breaks it (maybe
  for historic reasons) -- although this is also an opportunity to
  clean up someone else's mess (in true XP style).


C dialect
=========

* Python 3.11 and newer versions use C11 without `optional features
 <https://en.wikipedia.org/wiki/C11_%28C_standard_revision%29#Optional_features>`_.
 The public C API should be compatible with C++.

* Python 3.6 to 3.10 use C89 with several select C99 features:

 - Standard integer types in ``<stdint.h>`` and ``<inttypes.h>``. We
   require the fixed width integer types.
 - ``static inline`` functions
 - designated initializers (especially nice for type declarations)
 - intermingled declarations
 - booleans
 - C++-style line comments

* Python versions before 3.6 used ANSI/ISO standard C (the 1989 version
 of the standard).  This meant (amongst many other things) that all
 declarations must be at the top of a block (not necessarily at the
 top of function).

* Don't use compiler-specific extensions, such as those of GCC or MSVC
 (e.g. don't write multi-line strings without trailing backslashes).

* All function declarations and definitions must use full prototypes
 (i.e. specify the types of all arguments).

* No compiler warnings with major compilers (gcc, VC++, a few others).

* ``static inline`` functions should be preferred over macros in new
 code.


Code lay-out
============

* Use 4-space indents and no tabs at all.

* No line should be longer than 79 characters.  If this and the
 previous rule together don't give you enough room to code, your code
 is too complicated -- consider using subroutines.

* No line should end in whitespace.  If you think you need significant
 trailing whitespace, think again -- somebody's editor might delete
 it as a matter of routine.

* Function definition style: function name in column 1, outermost
 curly braces in column 1, blank line after local variable
 declarations.

 .. code-block::
    :class: good

    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;
    }

* Code structure: one space between keywords like ``if``, ``for`` and
 the following left paren; no spaces inside the paren; braces are
 required everywhere, even where C permits them to be omitted, but do
 not add them to code you are not otherwise modifying.  All new C
 code requires braces.  Braces should be formatted as shown:

 .. code-block::
    :class: good

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

* The return statement should *not* get redundant parentheses:

 .. code-block::
    :class: bad

    return(albatross); /* incorrect */

 Instead:

 .. code-block::
    :class: good

    return albatross; /* correct */

* Function and macro call style: ``foo(a, b, c)`` -- no space before
 the open paren, no spaces inside the parens, no spaces before
 commas, one space after each comma.

* Always put spaces around assignment, Boolean and comparison
 operators.  In expressions using a lot of operators, add spaces
 around the outermost (lowest-priority) operators.

* Breaking long lines: if you can, break after commas in the outermost
 argument list.  Always indent continuation lines appropriately,
 e.g.:

 .. code-block::
    :class: good

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

* When you break a long expression at a binary operator, braces
 should be formatted as shown:

 .. code-block::
    :class: good

    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 */
    }

 It's OK to put operators at ends of lines, especially to be
 consistent with surrounding code.
 (See :ref:`PEP 8 <pep8-operator-linebreak>` for a longer discussion.)

* Vertically align line continuation characters in multi-line macros.

* Macros intended to be used as a statement should use the
 ``do { ... } while (0)`` macro idiom,
 without a final semicolon.
 Example:

 .. code-block::
    :class: good

    #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`` file local macros after use.

* Put blank lines around functions, structure definitions, and major
 sections inside functions.

* Comments go before the code they describe.

* All functions and global variables should be declared static unless
 they are to be part of a published interface.

* For external functions and variables, we always have a declaration
 in an appropriate header file in the "Include" directory, which uses
 the ``PyAPI_FUNC()`` macro and ``PyAPI_DATA()`` macro, like this:

 .. code-block::
    :class: good

    PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);

    PyAPI_DATA(PyTypeObject) PySuper_Type;


Naming conventions
==================

* Use a ``Py`` prefix for public functions; never for static
 functions.  The ``Py_`` prefix is reserved for global service
 routines like ``Py_FatalError``; specific groups of routines
 (e.g. specific object type APIs) use a longer prefix,
 e.g. ``PyString_`` for string functions.

* Public functions and variables use MixedCase with underscores, like
 this: ``PyObject_GetAttr``, ``Py_BuildValue``, ``PyExc_TypeError``.

* Occasionally an "internal" function has to be visible to the loader;
 we use the ``_Py`` prefix for this, e.g.: ``_PyObject_Dump``.

* Macros should have a MixedCase prefix and then use upper case, for
 example: ``PyString_AS_STRING``, ``Py_PRINT_RAW``.

* Macro parameters should use ``ALL_CAPS`` style,
 so they are easily distinguishable from C variables and struct members.


Documentation Strings
=====================

* Use the ``PyDoc_STR()`` or ``PyDoc_STRVAR()`` macro for docstrings
 to support building Python without docstrings (``./configure
 --without-doc-strings``).

* The first line of each function docstring should be a "signature
 line" that gives a brief synopsis of the arguments and return value.
 For example:

 .. code-block::
    :class: good

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

 Always include a blank line between the signature line and the text
 of the description.

 If the return value for the function is always ``None`` (because there
 is no meaningful return value), do not include the indication of the
 return type.

* When writing multi-line docstrings, be sure to always use backslash
 continuations, as in the example above, or string literal
 concatenation:

 .. code-block::
    :class: good

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

 Though some C compilers accept string literals without either:

 .. code-block::
    :class: bad

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

 not all do; the MSVC compiler is known to complain about this.


Copyright
=========

This document has been placed in the public domain.

You are viewing proxied material from gopher.fnord.one. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.