Core Python Programming (2nd Edition)

3.4. Basic Style Guidelines
Comments
You do not need to be reminded that comments are useful both to you and those who come after you.
This is especially true for code that has been untouched by man (or woman) for a time (that means
several months in software development time). Comments should not be absent, nor should there be
novellas. Keep the comments explanatory, clear, short, and concise, but get them in there. In the end,
it saves time and energy for everyone. Above all, make sure they stay accurate!
Documentation
Python also provides a mechanism whereby documentation strings can be retrieved dynamically through
the __doc__ special variable. The first unassigned string in a module, class declaration, or function
declaration can be accessed using the attribute obj.__doc__ where obj is the module, class, or function
name. This works during runtime too!
Indentation
Since indentation plays a major role, you will have to decide on a spacing style that is easy to read as
well as the least confusing. Common sense also plays a role in choosing how many spaces or columns to
indent.
1 or 2 Probably not enough; difficult to determine which block of code statements belong to
8 to 10 May be too many; code that has many embedded levels will wrap around, causing the source
to be difficult to read
Four spaces is very popular, not to mention being the preferred choice of Python's creator. Five and six
are not bad, but text editors usually do not use these settings, so they are not as commonly used. Three
and seven are borderline cases.
As far as tabs go, bear in mind that different text editors have different concepts of what tabs are. It is
advised not to use tabs if your code will live and run on different systems or be accessed with different
text editors.
Choosing Identifier Names
The concept of good judgment also applies in choosing logical identifier names. Decide on short yet
meaningful identifiers for variables. Although variable length is no longer an issue with programming
languages of today, it is still a good idea to keep name sizes reasonable length. The same applies for
naming your modules (Python files).
Python Style Guide(s)
Guido van Rossum wrote up a Python Style Guide ages ago. It has since been replaced by no fewer than