PEP: 7 Title: Style Guide for C Code Version: $Revision$ Author: guido@python.org (Guido van Rossum) Status: Active Type: Informational 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]. 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 - Use ANSI/ISO standard C (the 1989 version of the standard). - 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). - Never use C++ style // one-line comments. - No compiler warnings with major compilers (gcc, VC++, a few others). Code lay-out - Use single-tab indents, where a tab is worth 8 spaces. - 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. 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 as shown: if (mro != NULL) { ... } else { ... } - The return statement should *not* get redundant parentheses: return Py_None; /* correct */ return(Py_None); /* incorrect */ - 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.: 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 DL_IMPORT() macro, like this: extern DL_IMPORT(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. References [1] PEP 8, Style Guide for Python Code, van Rossum, Warsaw http://www.python.org/peps/pep-0008.html Copyright This document has been placed in the public domain. Local Variables: mode: indented-text indent-tabs-mode: nil End: