Artificial Intelligence

Simplified Python Coding Standards


Last updated Tue. 1/28/2020
Back to 656 home page
Back to Reva Freedman's home page

Introduction

  • Coding standards, including formatting and documentation are important because the human reader is one of the most important users of program source.
  • These rules have been set up to create the most clarity while reducing redundant documentation as much as possible.
  • Corrections and suggestions are invited.

    • Use of these Rules

  • These rules are a simple set that suffice for beginning programs.
  • They include program formatting rules as well as standards for this course.
  • For larger or more complex projects you should use PEP 8, but you still need to follow the course standards for this class.

    • Philosophy

  • Guido van Rossum says: Code is read much more often than it is written.
  • PEP 20 says: Readability counts.

    • Program Organization

  • Put class definitions in separate files.

    • Overall Program Formatting

  • Do not put more than one statement per line.
  • Lines should not exceed 79 characters.
  • Comment lines should not exceed 72 characters.
  • Consistency is more important than any specific rule.

    • Program Header

  • A header similar to the following should appear at the top of your main program:
    • 
# Class:     CSCI 656
# Program:   Assignment 1
# Author:    Your Name
# Z-number:  z1234567
# Date Due:  mm/dd/yy

# Purpose:   A short indication of what the program does

# Execution: Command to execute your program, e.g., ./hw1.exe
#            (should match directions on assignment sheet)

# Notes:     (optional) any special notes to your T.A. or other readers

    Format of Names

  • Python prefers names of variables and functions to be written as follows:
  • The following style is also acceptable:
  • Name format should be consistent within a program.
  • Constants should be written in all caps with underscores.
  • One-letter names are permitted for temporary variables with no intrinsic meaning, such as subscripts and loop counters.

    • Variable Names

  • In general, the base of a variable name should be a noun, with adjectives used to make it specific, e.g., avg_height.
  • Names should be descriptive, e.g., avg_height rather than h or hgt.
  • In general, abbreviations should be avoided; as above, height is preferable to hgt. Abbreviations can be useful for long or frequently repeated words.
  • If abbreviations are used, they must be spelled consistently throughout your program, i.e., if you use avg_height for average height, then you should use avg_weight for average weight and not ave_ or average_.

    • Function Names

  • In general, function names should start with a verb and state what that verb refers to, e.g., count_lines().
  • The same rules on abbreviations for variable names apply to function names as well.

    • Comment Format

  • Comments should have a '#' in column 1 followed by a space.
  • Do not use '#' at the end of comment lines, i.e., do not enclose comments in boxes.

    • Section Documentation

  • Each section of code should be preceded by a comment that explains what the code does or what that group of variables is used for.
  • Section documentation should be preceded and followed by a blank line. Additional blank lines before logical divisions of the program and before functions may be profitably used to indicate the structure of the program. Be consistent.
  • If you use lines of *'s to set off sections of code, they should be the same length.
  • Section documentation should always start in column 1.

    •     The following examples show the size of chunk that should be commented. 

    # Loop to accept and process user-supplied glucose measurements

# Decide if gizmos or widgets are to be used

# Calculate and store averages and standard deviations of measurements

        Some programs are longer or more complex than others. That means that your main program may have several sections while a function that only does one thing may have only one.

        Occasionally, for a complex formula, a section will be only one line long: 

    # calculate the area of the triangle: semi is semiperimeter
# s1, s2, and s3 are sides 

area = sqrt(semi * (semi - s1) * (semi - s2) * (semi - s3))
  • It is rarely but occasionally useful to put a comment on the same line as code.
    •  ...    # end I/O loop
        If you find yourself frequently needing such comments, you should consider changing your nesting style.

    Documentation of Variables

  • Even though variables don't need to be declared in Python, they still need to be documented. Variables should be organized into groups at the top of each function (or main program), and each group should be labeled as to their purpose:

    • # Item subtotals
#     tot_items = total number of items
#     tot_cost  = total cost

        Horizontal alignment of variable names, as in the above examples, is encouraged but not required.

    Indentation and Continuation Lines

  • Indentation of 4 spaces per level is preferred.
  • Breaking lines inside a parenthesis or other grouping is preferred.
  • Consistent and clear intentation of continuation lines is required. PEP 8 gives a couple of options

    • How to Indent

  • Spaces are preferred to tabs or a mixture of tabs and spaces.
        Spaces are preferred because they will display correctly in any configuration.
  • Any good editor will have a setting that prevents spaces from being converted to tabs.
  • If you use tabs in spite of this warning, you are responsible for making sure your program will display correctly on turing/hopper.
        Unix defaults to tabs every 8 characters.
  • As a further warning, in some cases Python 3 will reject mixtures of tabs and spaces.

    • Horizontal white space

  • White space should be used before and after '=' and comparison operators ('= =', '<', etc.):
  • Do not put white space after a left parenthesis, bracket or brace, or before a right parenthesis, bracket or brace.

    • Functions

  • Functions should be documented like sections, plus some indication of the arguments and return value. If the function updates one or more of its arguments (or values they point to), that should be noted also.
    • 
# Calculate the area of a triangle using Hero's formula

# Arguments: sides of the triangle

# Returns:   the area of the triangle
#            -1 if the lengths do not represent a valid (closed) triangle

# Additional section documentation as required.
  • A function must not wipe out its input.

    • Restricted Constructs

  • Break may only be used to escape from an otherwise infinite I/O loop.
  • Do not use any construct that depends on a specific text encoding. Therefore, for example, you may not use ord.

    • Pythonic Style

  • In general, use list comprehensions instead of loops. Except for complex cases, loops should not be necessary except for reading a file.
  • Don't write if expr == True. Write if expr instead.

    • Good Practices

    The following good practices are encouraged because they simplify program debugging and updating. However, they are not required.

  • Use temporary variables when it might be useful to examine a field when debugging. For example,
    • total_area = (complex formula)
return total_area

         is easier to debug than 

    return (complex formula)
  • In general, don't nest if or while statements more than three deep.
        Although the compiler can read it, most human beings have to count on their fingers by that point.