CIT 591: Basic style rules
Fall 2012, David Matuszek

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.

General style rules

Use meaningful names

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."""
     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"
             move = choose_computers_move()
             game_over = make_move("computer", move)
             player = "human"

There are some cases where it is better not to use a meaningful name. The index of a for loop is usually just i (or 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: grades).

There are two common naming conventions for variables and functions: camelCaseNames, and names_with_underscores. In this course we will use underscores.

Use proper spacing and indentation

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:

Style rules for functions

Name functions with verbs or verb phrases

Functions do something, and their names should indicate that. For example, results is not a good function name; printResults is a much better function name.

A lot of words in English are both nouns and verbs; for example, move. When used as the name of a function, it is read as being a verb, so use it that way.

Function names should tell what the function does

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.

Functions should be single-purpose

Each function should do only one thing.

As an important special case, a function should not both compute something and do input/output. A printResults function should not compute and print results.

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 makeMove. 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,"

Functions should be short

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.

Parameter lists should be short

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.

Avoid using global variables

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.