Python Style Rules and Guidelines

Beauty is more important in computing than anywhere else in technology because software is so complicated. Beauty is the ultimate defense against complexity.
Good programmers know what's beautiful and bad ones don't.
-- David Gelernter, Machine Beauty

Programming is best regarded as the process of creating works of literature, which are meant to be read.
-- Donald Knuth, Literate Programming

The Zen of Python
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
-- Tim Peters

Always obey the rules below. They are prefixed by R. There is a grade penalty for breaking them. Like grammatical mistakes in English, if you break the rules it is quite distracting, and may cause serious confusion for your reader.

If you do not generally follow the Guidelines below, prefixed below by G, your program becomes hard to read, but violations are not as serious as breaking rules, and exceptions are sometimes appropriate.

These rules and guidelines are generally consistent with the style guide of Guido van Rossum (the inventor of Python) and Barry Warsaw.

1. R: Start every assignment file with a special comment line containing the assignment number and the names and usernames of all your assignment team members. For example:
   # a2 by Wendy Wiz, wwiz, and Harry Hacker, hhacker
    (Alternatively, this information may be at the beginning of a module documentation string at the start of the file.)
2. R: Consistently use one of the following convention for long names:
   • Underscore-separated names use only lower-case letters, separating words with underscores, for example interest_rate.
   • Camel-case names separate words by capitalizing the first letter of every word (except the first, unless it is a class name, as noted below), for example interestRate.
   • Run-together names do not separate words, for example interestrate.

   Run-together names, for example interestrate, are occasionally used in the Python APIs, but they are hard to read and should be avoided except for very short names. Underscore-separated and camel-case names are both extensively used in the Python APIs, but it is not good style to use both styles for names of the same sort in the same program, for that is distracting and makes it harder to remember names. The recommended usage is underscore-separated for variable and function names, camel-case for class names, and run-together lower-case for module names.

   Constants are variables that are not assigned after their initialization, and usually (the notion is a bit fuzzy in this respect) have values that are determined at compile time. They may be indicated by all-upper-case underscore-separated names, for example INTEREST_RATE. If so, use this style consistently throughout a program.

   All names, except those of classes and upper-case-only constants, should begin with lower-case letters.

3. G: Use descriptive names for all identifiers (variable, method, and class names). Generally avoid single letter names such as a and x . There are a couple times when short names are appropriate:
   • the identifier is being used as a index counter (in which case i and j are fine)
   • all uses are within a few lines of its declaration, and its declaration makes clear its significance.
     
4. Make good use of white space.
   • R: Do not use tab characters, since printing and editing environments differ in how they interpret tabs.
   • R: Do not put more characters on a line than fit on one line in all the printing and editing environments that you code will be exposed to. For this course, that is at most 85. When in doubt, limit yourself to 80 characters per line. Continue lines with an extra level of indentation.
   • G: Use blank lines to delineate different areas of your code:
     • after a group of import declarations
     • between function declarations
     • separating logically related groups of code

     Using more than one blank line in a row is usually a waste of pixels and paper, and makes program navigation harder.

     (Code in class materials frequently contains fewer blank lines than would be otherwise desirable due to unfortunate display limitations.)

   • G: Use a space after each comma, before each left brace, and around most binary operators.
     
5. R: Always use the same number of spaces for one level of indentation. Four spaces is recommended. Eight spaces, the standard tab amount, is way too much, and one or two is too little.
6. G: Declare constants to give names to magic numbers. A magic number is any number other than -1, 0, 1, and 2. This forces you to give meaningful names to mysterious quantities, which goes a long way toward making programs self-documenting.
7. G: Use meaningful comments to clarify your program.
   • Provide comments for program characteristics that are not readily apparent from the names you have chosen and knowledge of common Python language mechanisms. Don't clutter up your program with comments that only say what is obvious from the code. Using good variable and function names greatly reduces the need for comments. Declaring variables to give names to numeric values helps a lot.
   • Use ## comments to indicate stubs and development notes (to be removed before the program is completed).
     
8. G: Clarity is the overriding style concern.
   1. Avoid unnecessarily complicated code. Rework the code if you see a better way (called refactoring, another precept of extreme programming).
   2. Clarity is more important than efficiency, unless the efficiency improvement is important to the application. (Programmer time is usually more expensive than computer time. Also, it is impossible to detect an efficiency improvement from most "improvements" programmers are tempted to make in the name of efficiency, and sometimes they actually slow the program down by making it more difficult for the compiler to perform optimizations.)
      
9. R: Avoid dead code that can never be reached due to local program structure. 
10. R: Order elements of your program file as follows (not all elements may be present in a program, and additional comments may be placed anywhere they are appropriate) :
    1. Initial comment as described in point 1 above
    2. import statements
    3. Global constand declarations (see following note)
    4. Global variable declarations (see following note)
    5. Function definitions
    6. Statements that execute the program (may be as little as one function call)
    Note: global constants and variables that are used by only one function, may be declared just before the function.
G: More guidelines for naming:
• Generally avoid abbreviations in names, including vowel dropping: e.g. use customerName instead of custName and message instead of msg. Exception: use num instead of numberOf, as in numFields instead of numberOfFields.
• Choose names from parts of speech so that program fragments make more sense as English
  • Function names: verbs or verb phrases
  • Boolean variable names: predicative verbs (which make sense following if), e.g. done, isFull
  • Other variables: nouns
• The following names are recommended for variables whose values are of the indicated type, provided the values are arbitrary or clear from the immediate context:
  • list: lst, ls (avoid using the letter l, which is easily confused with the number 1)
  • sequence: seq
  • string: s
  • character: c
  • tuple: t, tup
  • integer: i, j, k, n, m
  • float: x, y, z
  • dictionary: d, dct
  • exception: e, exc
  • function: f, fun
  • object: o, obj (o is much used in the Python documentation, but is easily confused with the number 0)
  • a value of any type: any
  • a value with multiple possible (but not arbitrary) types: thing
• Avoid the use of negative boolean variable names; for example use done instead of not_done.
11. R: If line breaks occur between elements of a list or tuple literal, or a parameter list, the elements should be indented to aligned vertically.
12. G: use pydoc string documentation. Strings that appear as the first statement in a module, or the first statement in a function or class body, are stored in the associated module, function, and class data structure as documentation. (By convension these are delimited by three double-quotes.) The built-in function help and the application pydoc distributed with Python make use of this information to provide on-line help and automatically generate html documentation, respectively.
13. G: Break up long declarations. If a method or class declaration is getting long (more than about 30 lines for a method and a page or two for a class), it is often a good idea to break it up.