Style rules are based on the principle that programs should be easy to understand. Programs that are easy to understand are easier to get correct in the first place, easier to debug when they aren't correct, and easier to maintain if they are used for any length of time. Here are just a few of the more important style rules.
As you name your variables and functions, you are basically making up a language. The quality and clarity of this language significantly affects how readable your program is. For example, if you were going to write a program to play a game (computer against human), you might start with something like this:
def playGame(): """Plays the game of X.""" setup() game_over = False player = decide_who_goes_first() while not game_over: if player == "human": move = get_humans_move() game_over = make_move("human", move) player = "computer" else: move = choose_computers_move() game_over = make_move("computer", move) player = "human" congratulate_or_taunt_human()
There are some cases where it is better not to use a meaningful name. The index of a
for loop is usually just
j, for a loop inside another loop).
Names of function parameters should be based on what the function does, not on what you expect to use it for. For example, if you have a function to remove whitespace from a string, then
string is good parameter name;
message_to_encode is not, because you might also use this function for other strings.
Variables usually hold "things," so give them names which are nouns (example:
coin). A list or array holds more than one thing, so use a plural noun (example:
There are two common naming conventions for variables and functions:
names_with_underscores. In this course we will use underscores.
The indentation rule for Python is to indent by 4 spaces (other languages may differ). IDLE does this automatically for you; and if you use the Tab key, IDLE converts it to spaces.
Some spacing rules for Python (and almost all other languages) are:
.). Binary operators include assignment (
=) and arithmetic (
,). If there is more on a line after a colon (
:), put a space after the colon.
Functions do something, and their names should indicate
that. For example,
results is not
a good function name;
a much better function name.
A lot of words in English are both nouns and verbs; for example,
When used as the name of a function, it is read as being a verb, so use
it that way.
The name should correctly imply what the
function does. For example,
printResults is a good
function name if and only if the function prints
results (and doesn't do something else). If the purpose of a function
changes as you develop the code, rename the function.
Each function should do only one thing.
As an important special case, a function should not both compute something and do input/output. A
function should not compute and
An action can, of course, have "sub-actions." In the example above, the
playGame function does one thing--it plays a game. In order
to do this, it has to call other functions, such as
So there are "higher level" functions and "lower level" functions, and
in each case, it's up to you to figure out the meaning of "single purpose,"
Whatever you may have heard in the past, it is much better to have a lot of short, single-purpose functions than a small number of do-everything functions. Shorter functions are easier to get correct and, as a bonus, they are easier to re-use in other parts of the program and in other programs.
At their largest, functions should still be short enough so that you can see the entire thing at once, without scrolling.
The more parameters a function needs, the harder it is to keep track of what they all are, or in what order you should put them. Long parameter lists also suggest that the function is trying to do too much.
In general, if a function can figure out something for itself, it should
not ask for that information as a parameter. For example, if a function
does something with a list, and needs to know the length of the list,
it should use the
len(list) function to find out,
rather than expect the length as an additional parameter.
The more important reasons for this rule are more complex than I want to talk about right now. Here are a couple of simpler reasons:
A variable should be global only if it really is needed everywhere throughout the program. Even then, you should prefer using parameters to pass the variable around, rather than making it global, unless this just clutters up your code too much.
Finally, trying to use a global variable defined in a different module (file) can result in bizarre and mysterious behavior.