python-peps/pep-0007.txt

242 lines
7.5 KiB
Plaintext
Raw Normal View History

2001-07-05 10:16:35 -04:00
PEP: 7
Title: Style Guide for C Code
Version: $Revision$
Last-Modified: $Date$
Author: Guido van Rossum <guido@python.org>, Barry Warsaw <barry@python.org>
2001-07-05 10:16:35 -04:00
Status: Active
2007-06-19 00:52:34 -04:00
Type: Process
2012-03-15 03:18:38 -04:00
Content-Type: text/x-rst
2001-07-05 10:16:35 -04:00
Created: 05-Jul-2001
Post-History:
2012-03-15 03:18:38 -04:00
2001-07-05 10:16:35 -04:00
Introduction
2012-03-15 03:18:38 -04:00
============
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
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]_.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
Note, rules are there to be broken. Two good reasons to break a
particular rule:
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
1. When applying the rule would make the code less readable, even for
someone who is used to reading code that follows the rules.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
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).
2001-07-05 10:16:35 -04:00
C dialect
2012-03-15 03:18:38 -04:00
=========
2001-07-05 10:16:35 -04:00
2016-09-07 13:55:40 -04:00
* Python versions before 3.6 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).
* Python versions greater than or equal to 3.6 use C89 with several
select C99 features:
2016-09-07 19:22:00 -04:00
- Standard integer types in ``<stdint.h>`` and ``<inttypes.h>``. We
require the fixed width integer types.
2016-09-07 13:55:40 -04:00
- ``static inline`` functions
- designated initializers (especially nice for type declarations)
- intermingled declarations
- booleans
2016-09-07 17:49:47 -04:00
- C++-style line comments
2016-09-07 13:55:40 -04:00
Future C99 features may be added to this list in the future
depending on compiler support (mostly significantly MSVC).
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Don't use GCC extensions (e.g. don't write multi-line strings
without trailing backslashes).
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* All function declarations and definitions must use full prototypes
(i.e. specify the types of all arguments).
2001-07-05 10:16:35 -04:00
2017-08-18 15:05:03 -04:00
* Only use C++ style // one-line comments in Python 3.6 or later.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* No compiler warnings with major compilers (gcc, VC++, a few others).
2001-07-05 10:16:35 -04:00
Code lay-out
2012-03-15 03:18:38 -04:00
============
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Use 4-space indents and no tabs at all.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* 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.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* 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.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Function definition style: function name in column 1, outermost
curly braces in column 1, blank line after local variable
declarations. ::
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
static int
extra_ivars(PyTypeObject *type, PyTypeObject *base)
{
int t_size = PyType_BASICSIZE(type);
int b_size = PyType_BASICSIZE(base);
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
assert(t_size >= b_size); /* type smaller than base! */
...
return 1;
}
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* 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::
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
if (mro != NULL) {
...
}
else {
...
}
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* The return statement should *not* get redundant parentheses::
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
return Py_None; /* correct */
return(Py_None); /* incorrect */
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* 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.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Always put spaces around assignment, Boolean and comparison
operators. In expressions using a lot of operators, add spaces
around the outermost (lowest-priority) operators.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Breaking long lines: if you can, break after commas in the outermost
argument list. Always indent continuation lines appropriately,
e.g.::
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
PyErr_Format(PyExc_TypeError,
"cannot create '%.100s' instances",
type->tp_name);
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* When you break a long expression at a binary operator, the
operator goes at the end of the previous line, and braces should be
formatted as shown. E.g.::
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
if (type->tp_dictoffset != 0 && base->tp_dictoffset == 0 &&
type->tp_dictoffset == b_size &&
(size_t)t_size == b_size + sizeof(PyObject *))
{
2012-03-15 03:18:38 -04:00
return 0; /* "Forgive" adding a __dict__ only */
}
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Put blank lines around functions, structure definitions, and major
sections inside functions.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Comments go before the code they describe.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* All functions and global variables should be declared static unless
they are to be part of a published interface
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* 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::
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
2001-07-05 10:16:35 -04:00
Naming conventions
2012-03-15 03:18:38 -04:00
==================
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* 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.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Public functions and variables use MixedCase with underscores, like
this: ``PyObject_GetAttr``, ``Py_BuildValue``, ``PyExc_TypeError``.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Occasionally an "internal" function has to be visible to the loader;
we use the ``_Py`` prefix for this, e.g.: ``_PyObject_Dump``.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
* Macros should have a MixedCase prefix and then use upper case, for
example: ``PyString_AS_STRING``, ``Py_PRINT_RAW``.
2001-07-05 10:16:35 -04:00
Documentation Strings
2012-03-15 03:18:38 -04:00
=====================
2012-03-15 03:18:38 -04:00
* Use the ``PyDoc_STR()`` or ``PyDoc_STRVAR()`` macro for docstrings
to support building Python without docstrings (``./configure
--without-doc-strings``).
2012-03-15 03:18:38 -04:00
For C code that needs to support versions of Python older than 2.3,
you can include this after including ``Python.h``::
2012-03-15 03:18:38 -04:00
#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 function docstring should be a "signature
2012-03-15 03:18:38 -04:00
line" that gives a brief synopsis of the arguments and return value.
For example::
2012-03-15 03:18:38 -04:00
PyDoc_STRVAR(myfunction__doc__,
"myfunction(name, value) -> bool\n\n\
Determine whether name and value make a valid pair.");
2012-03-15 03:18:38 -04:00
Always include a blank line between the signature line and the text
of the description.
2012-03-15 03:18:38 -04:00
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.
2012-03-15 03:18:38 -04:00
* When writing multi-line docstrings, be sure to always use backslash
continuations, as in the example above, or string literal
concatenation::
2012-03-15 03:18:38 -04:00
PyDoc_STRVAR(myfunction__doc__,
"myfunction(name, value) -> bool\n\n"
"Determine whether name and value make a valid pair.");
2012-03-15 03:18:38 -04:00
Though some C compilers accept string literals without either::
2012-03-15 03:18:38 -04:00
/* BAD -- don't do this! */
PyDoc_STRVAR(myfunction__doc__,
"myfunction(name, value) -> bool\n\n
Determine whether name and value make a valid pair.");
2012-03-15 03:18:38 -04:00
not all do; the MSVC compiler is known to complain about this.
2001-07-05 14:53:01 -04:00
References
2012-03-15 03:18:38 -04:00
==========
2001-07-05 14:53:01 -04:00
2012-03-15 03:18:38 -04:00
.. [1] PEP 8, "Style Guide for Python Code", van Rossum, Warsaw
(http://www.python.org/dev/peps/pep-0008)
2001-07-05 14:53:01 -04:00
2001-07-05 10:16:35 -04:00
Copyright
2012-03-15 03:18:38 -04:00
=========
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
This document has been placed in the public domain.
2001-07-05 10:16:35 -04:00
2012-03-15 03:18:38 -04:00
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End: