Appendix B: Composing Clear Code

This page complements the official Style Guide for Python Code by providing some recommendations that are appropriate for those who are new to computer programming.

Coding

Keep programs, functions, and methods short and manageable.
Use language-specific idioms.
Use straightforward logic and flow-of-control.
Avoid magic numbers (numbers other than -1, 0, 1, and 2); instead, give them meaningful symbolic names. Such names are called constants.

Naming Conventions

When choosing names for your variables, functions, methods, and classes:

Use meaningful names that convey the purpose of the variable, function, method, or class. Choose names that are easy to pronounce, and avoid cryptic abbreviations. For example, use wagePerHour or hourlyWage instead of wph. Use polygon instead of p or poly or pgon.
Be consistent.
Name boolean variables, functions, and methods so that their meaning is unambiguous, e.g., isPrime or isEmpty() or contains().
Use shorter names (e.g., i) for short-lived variables and loop-index variables. Use more descriptive names for variables that serve an important purpose.
Avoid generic names like foo or tmp and meaningless names like fred. Use terminology from the application domain when possible.
Name a constant variable by its meaning, not its value, e.g., name your variable DAYS_PER_WEEK instead of SEVEN.

Identifier Naming Rules Examples

Variable A short, but meaningful, name that communicates
to the casual observer what the variable represents,
rather than how it is used. Begin with a lowercase letter
and use camel case (mixed case, starting with lower case). mass hourlyWage isPrime

Constant Variable Use all capital letters and separate internal words
with the underscore character. N BOLTZMANN MAX_HEIGHT

Class A noun that communicates what the class represents.
Begin with an uppercase letter and use camel case for
internal words. class Complex class Charge class PhoneNumber

Function
or Method A verb that communicates what the function or method
does. Begin with a lowercase letter and use camelCase for
internal words. move() draw() enqueue()

Identifier	Naming Rules	Examples
Variable	A short, but meaningful, name that communicates to the casual observer what the variable represents, rather than how it is used. Begin with a lowercase letter and use camel case (mixed case, starting with lower case).	`mass hourlyWage isPrime`
Constant Variable	Use all capital letters and separate internal words with the underscore character.	`N BOLTZMANN MAX_HEIGHT`
Class	A noun that communicates what the class represents. Begin with an uppercase letter and use camel case for internal words.	`class Complex class Charge class PhoneNumber`
Function or Method	A verb that communicates what the function or method does. Begin with a lowercase letter and use camelCase for internal words.	`move() draw() enqueue()`

Commenting

Programmers use comments to annotate a program and help the reader (or grader) understand how and why your program works. As a general rule, the code explains to the computer and programmer how the program works; the comments explain to the programmer what the program does. Comments can appear anywhere within a program where whitespace is allowed. Python ignores comments.

A comments begins with # (the pound or number-sign character) and ends at the end of the line on which the # appears. Any text from the # to the end of the line is ignored.

There is no widely agreed upon set of rules. Good programmers write code that documents itself.

Make sure that comments agree with the code. Be careful to update the comments when you update the code.
Do not write comments that merely restate the code. Generally, comments should describe what or why you are doing something, rather than how.
i += 1 # Increment i by one.
Comment any potentially confusing code, or better yet, rewrite the code so that it isn't confusing.
Include a comment at the beginning of each file with the name of the file and your name.
Comment each function and method with a description of what it does. Include what it takes as input, what it returns as output, and any side effects. Use the parameter names in your description.
# Rearrange the elements in the array a in random order # using Knuth's shuffling algorithm. def shuffle(a): ...

Whitespace

Programmers use whitespace in their code to make it easier to read.

Don't put more than one statement on a line.
Use blank lines to separate your code into logical sections.
Put a space between all binary operators (e.g., <=, =, +) and their operands. One possible exception is to emphasize precedence.
a*x + b
Put a space after each comma in an argument list.

Put space after each comment delimiter.

#This comment has no space
#after the delimiter and is
#difficult to read.

# This comment has a
# space after the delimiter
# and is easier to read.

Do not put spaces between a module name, the . separator, and a name defined in that module. Also do not put spaces between an object name, the . separator, and a method name.
Within a function or method call, do not put spaces between a function or method name and the following left parenthesis.
Include blank lines to improve readability by grouping blocks of related code.

Use spaces to align parallel code whenever it enhances readability.

n      = int(sys.argv[1])      # size of population
trials = int(sys.argv[2])      # number of trials

Indenting

Programmers format and indent their code to reveal structure, much like an outline. In most modern programming languages, indentation is important to the human reader of the program, but is ignored by the computer. With the Python language, indentation is not ignored by the computer; indentation is part of the program's logic.

Avoid lines longer than 72 characters.
Do not put more than one statement on a line.
Indent a fixed number of spaces. Python programmers almost universally use a 4 space indentation scheme.
Always use spaces instead of tabs. Modern IDEs (including IDLE) insert spaces when you type the Tab key — these are known as soft tabs. Hard tabs are obsolete: in ancient times, they were used for data compression.

Q & A

Q. Are there any official coding standards?

A. Yes. See the Style Guide for Python Code.

Q. Any good references on programming style?

A. The Practice of Programming by Brian W. Kernighan and Rob Pike is a classic.

Q. How can I easily indent my code?

A. Use an editor designed for writing code. For example, in IDLE, if you select a region of code and hit the Tab key, IDLE will reindent it for you automatically.

Q. How can I write unmaintainable code?

A. Here's one guide to designing unmaintainable code.