Coding Standard

for

Computer Projects

When you convert a design document into Python source code, one of your primary goals should be to write the source code and internal documentation in such a way so that it is easy to verify that the source code conforms to the design, and so that it is easy to debug, test, and maintain the source code. The coding standard below is designed to assist you in achieving this goal.

1. No Personal Information

Do not include any personal information, such as your name or MSU PID, in any of your source code files. All project solutions are sent off campus to a software system which compares source code files for similarities.

2. Source Code Format

Source code lines will be no more than 120 characters long. Break long lines into multiple shorter lines using the continuation character ("\").

Only one statement will be included on a given line of the source code.

Use four spaces for indentation.

Blank lines and spaces will be used to enhance the readability of both source statements and comments.

All import statements will appear after the source code header and before any other Python code in the program.

All function definitions will appear after the import statements and before any other Python code in the program.

3. Source Code Header

Main source code file will contain an introductory block of comments that identifies the assignment and gives a brief overview of the program. For example:

###########################################################

# Computer Project #5

#

# Algorithm

# prompt for an integer

# input an integer

# loop while not end-of-data

# call function to count number of digits in integer

# output the number of digits

# prompt for an integer

# input an integer

# display closing message

###########################################################

4. Descriptive Comments

The source code will include comments that describe the functionality of significant blocks of code. Comments are particularly important before all blocks of code that perform major data manipulations or error processing.

For readability, each comment will be indented at the same level as the block of code that it describes or, if it fits within the 120-character limit and describes just a single line of code, to the right of that line.

See Section 3.3.1 Readability in the text starting on page 167.

Place comments to indicate:

• The purpose of objects that are not clear from their names.
• Where something is "tricky", "clever", or "unusual"; if it required thought on your part, it should be commented.

If it was hard to write, it is probably hard to read. Add a comment.

5. Mnemonic Identifiers

Meaningful identifiers taken from the problem domain will be used for all names. Furthermore, a name will be used for only one purpose (the same name will not be used for more than one purpose).

6. Symbolic Constants

Symbolic constants will be used instead of embedding arbitrary numeric and character constants in the source code. Use "upper with under" style for all symbolic constants:

HEAT_OF_FUSION = 79.71 # Calories to melt one gram of ice

7. Variable and Function Names

Use "lower with under" style for all variable and function names. In some situations, it is appropriate to append type information to variable names as a visual reminder about the purpose of those variables:

student_count = 0 # Number of students in class

fahrenheit_float = 0.0 # Temperature in Fahrenheit

8. Function Header and Class Method Header

Using docstrings (delimited by triple double-quotes), each function will contain an introductory block of comments that explains the purpose of the function and describes all information passed to the function, modified by the function, and returned by the function (parameters and global data objects).  It will also describe any assumptions about the information passed to the function that is needed for the function to work correctly. Do the same for class methods. For example:

    def count_digits( value ):

        """

        Count the number of digits in an integer value.

        value:  The value to be processed (int)

        Returns:  The number of digits in value (int)

        """

def add_assignment( grade_book, possible_pts ):

"""

Adds a new assignment to a grade book.

grade_book: the grade book (dict)

maps assignment names (str) to grad dicts,

where a grade dict maps student PIDS (str)

to grades (float)

grade_book is both read and modified

possible_pts: the total points possible,

must be positive

"""

9. Class Names

Use "CamelCase" style for all class names:

class SalariedEmployee

class HourlyEmployee

Guido van Rossum, the creator of Python, has a lengthy style guide:

http://www.python.org/dev/peps/pep-0008/

That style guide is an excellent resource for more complex situations not described in this document.