Style Guide for C Code

pep-0000.txt

@@ -28,6 +28,7 @@ Index by Category
  I     4  pep-0004.txt  Deprecation of Standard Modules        von Loewis
  I     5  pep-0005.txt  Guidelines for Language Evolution      Prescod
  I     6  pep-0006.txt  Bug Fix Releases                       Aahz
+ I     7  pep-0007.txt  Style Guide for C Code                 van Rossum
 
  Other Informational PEPs
 
@@ -125,6 +126,7 @@ Numerical Index
  I     4  pep-0004.txt  Deprecation of Standard Modules        von Loewis
  I     5  pep-0005.txt  Guidelines for Language Evolution      Prescod
  I     6  pep-0006.txt  Bug Fix Releases                       Aahz
+ I     7  pep-0007.txt  Style Guide for C Code                 van Rossum
  I    42  pep-0042.txt  Small Feature Requests                 Hylton
  SF  100  pep-0100.txt  Python Unicode Integration             Lemburg
 

pep-0007.txt

@@ -0,0 +1,151 @@
+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.
+
+    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.
+
+
+Copyright
+
+    This document has been placed in the public domain.
+
+
+
+Local Variables:
+mode: indented-text
+indent-tabs-mode: nil
+End: