diff --git a/pep-0007.txt b/pep-0007.txt --- a/pep-0007.txt +++ b/pep-0007.txt @@ -2,210 +2,221 @@ Title: Style Guide for C Code Version: $Revision$ Last-Modified: $Date$ -Author: guido@python.org (Guido van Rossum) +Author: Guido van Rossum Status: Active Type: Process +Content-Type: text/x-rst Created: 05-Jul-2001 Post-History: Introduction +============ - This document gives coding conventions for the C code comprising - the C implementation of Python. Please see the companion - informational PEP describing style guidelines for Python code[1]. +This document gives coding conventions for the C code comprising +the C implementation of Python. Please see the companion +informational PEP describing style guidelines for Python code [1]_. - Note, rules are there to be broken. Two good reasons to break a - particular rule: +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). +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 +========= - - Use ANSI/ISO standard C (the 1989 version of the standard). - This means (amongst many other things) that all declarations - must be at the top of a block (not necessarily at the top of - function). +* Use ANSI/ISO standard C (the 1989 version of the standard). + This means (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 GCC extensions (e.g. don't write multi-line strings - without trailing backslashes). +* Don't use GCC extensions (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). +* All function declarations and definitions must use full + prototypes (i.e. specify the types of all arguments). - - Never use C++ style // one-line comments. +* Never use C++ style // one-line comments. - - No compiler warnings with major compilers (gcc, VC++, a few - others). +* No compiler warnings with major compilers (gcc, VC++, a few + others). Code lay-out +============ - - Use 4-space indents and no tabs at all. +* 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. + :: - - 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. + static int + extra_ivars(PyTypeObject *type, PyTypeObject *base) + { + int t_size = PyType_BASICSIZE(type); + int b_size = PyType_BASICSIZE(base); - - 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. + assert(t_size >= b_size); /* type smaller than base! */ + ... + return 1; + } - - Function definition style: function name in column 1, outermost - curly braces in column 1, blank line after local variable - declarations. +* Code structure: one space between keywords like 'if', 'for' and + the following left paren; no spaces inside the paren; braces may be + omitted where C permits but when present, they should be formatted as + shown: + :: - static int - extra_ivars(PyTypeObject *type, PyTypeObject *base) - { - int t_size = PyType_BASICSIZE(type); - int b_size = PyType_BASICSIZE(base); + if (mro != NULL) { + ... + } + else { + ... + } - assert(t_size >= b_size); /* type smaller than base! */ - ... - return 1; - } +* The return statement should *not* get redundant parentheses: + :: - - Code structure: one space between keywords like 'if', 'for' and - the following left paren; no spaces inside the paren; braces may be - omitted where C permits but when present, they should be formatted as - shown: + return Py_None; /* correct */ + return(Py_None); /* incorrect */ - if (mro != NULL) { - ... - } - else { - ... - } +* 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.: + :: - - The return statement should *not* get redundant parentheses: + PyErr_Format(PyExc_TypeError, + "cannot create '%.100s' instances", + type->tp_name); - return Py_None; /* correct */ - return(Py_None); /* incorrect */ +* When you break a long expression at a binary operator, the + operator goes at the end of the previous line, e.g.: + :: - - 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. + 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 */ - - Always put spaces around assignment, Boolean and comparison - operators. In expressions using a lot of operators, add spaces - around the outermost (lowest-priority) operators. +* 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, like this: + :: - - Breaking long lines: if you can, break after commas in the - outermost argument list. Always indent continuation lines - appropriately, e.g.: - - PyErr_Format(PyExc_TypeError, - "cannot create '%.100s' instances", - type->tp_name); - - - When you break a long expression at a binary operator, the - operator goes at the end of the previous line, e.g.: - - 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 */ - - - 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, like this: - - PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); + PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *); 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. +* 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`. Documentation Strings +===================== - - Use the PyDoc_STR() or PyDoc_STRVAR() macro for docstrings to - support building Python without docstrings (./configure - --without-doc-strings). +* Use the `PyDoc_STR()` or `PyDoc_STRVAR()` macro for docstrings to + support building Python without docstrings (./configure + --without-doc-strings). - For C code that needs to support versions of Python older than - 2.3, you can include this after including Python.h: + For C code that needs to support versions of Python older than + 2.3, you can include this after including 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 + #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 - - The first line of each fuction docstring should be a "signature - line" that gives a brief synopsis of the arguments and return - value. For example: +* The first line of each fuction docstring should be a "signature + line" that gives a brief synopsis of the arguments and return + value. For example: + :: - PyDoc_STRVAR(myfunction__doc__, - "myfunction(name, value) -> bool\n\n\ - Determine whether name and value make a valid pair."); + 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. + 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. + 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: +* When writing multi-line docstrings, be sure to always use + backslash continuations, as in the example above, or string + literal concatenation: + :: - PyDoc_STRVAR(myfunction__doc__, - "myfunction(name, value) -> bool\n\n" - "Determine whether name and value make a valid pair."); + 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: + Though some C compilers accept string literals without either: + :: - /* BAD -- don't do this! */ - PyDoc_STRVAR(myfunction__doc__, - "myfunction(name, value) -> bool\n\n - Determine whether name and value make a valid pair."); + /* 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. + not all do; the MSVC compiler is known to complain about this. References +========== - [1] PEP 8, Style Guide for Python Code, van Rossum, Warsaw - http://www.python.org/dev/peps/pep-0008/ +.. [1] PEP 8, "Style Guide for Python Code", van Rossum, Warsaw (http://www.python.org/dev/peps/pep-0008) Copyright +========= - This document has been placed in the public domain. +This document has been placed in the public domain. -Local Variables: -mode: indented-text -indent-tabs-mode: nil -End: +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: