[Python-Dev] "Becoming a Python Developer"

[Guido van Rossum]

Nice work, Andrew!

I surely hope this will bring us some new contributors...

Some answers to your XXX marks:

> You like hacking on language interpreters.  (XXX is that a bit
> snarky? not sure I phrased that well...)

Sounds fine to me, or you could extend to "large software packages".

> Python is over 10 years old, and its development process is quite
> (XXX elaborate? evolved? mature?)

I'd say mature.

> Python is developed by a group of about 30 people,

True, but may sound off-putting to would-be contributors.  Maybe you
can add that lots of others contribute significantly?  (E.g. ask Fred
how many folks have contributed to the docs!)

> XXX should something be written about CPython / JPython / Stackless
> / Python.NET? I only know about CPython.

Explaining the distinction would be helpful, and you could add that
for Java programmers, participating in Jython would be a logical step.

> Guido van Rossum has the title of Benevolent Dictator For Life, or
> BDFL.

Lest people who aren't familiar with Python culture (or those who are
but lack a sense of humor) take this at face value, can you explain
that this is a tongue-in-cheek title?

The section on CVS is redundant -- this information is already on the
SF website, isn't it?  (Or most of it.)  I don't think detailed
instructions need to be in a high-level motivational article -- a link
to http://sourceforge.net/cvs/?group_id=5470 is all that's needed
(like you do for other services).

> diff -C2. (XXX is that correct?)

I use "diff -c" which seems to have the same effect.

> Python's standard style, described at XXX.


Alas, there's no description.  Let me try to summarize the rules here.


C dialect:

- Use ANSI/ISO standard C (the 1989 version of the standard).

- 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.

- 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.


I'm sure there's more.  I'll make this into a PEP.

--Guido van Rossum (home page: http://www.python.org/~guido/)