CP104: Programming Standards

Coding Standards

Coding Standards refers to how a program is written in terms of line spacing, type of indentation, and naming conventions. There may be style conventions for a programming language as a whole but the organization that you work for typically has their own coding style conventions. For CP104, our style requirements are:

All variable, constant, and function names should be descriptive. Single letter variable names, with some exceptions, are rarely descriptive enough.
All variable and function names use lower case letters and underscores between words. Examples: date, month, day_of_week, home_address, price_per_sq_in, get_name().
All constant values use capital letters and underscores between words. Examples: GST, DAYS_IN_WEEK, SPEED_OF_LIGHT.
Format your code using Eclipse/PyDev. If you configure Eclipse/PyDev as we suggest in lab 1, code will be automatically formatted. Otherwise, while in the text editor, select Source / Format Code to tidy up your code.
Use blank lines liberally. No need to crowd your code together, but don't put a blank line between every two lines of code. Group code according to its function.
All output should be formatted using the f-string method. This technique is taught in the CP104: Formatted Output lab.

CP104 follows, for the most part, the style recommended by Guido van Rossum and Barry Warsaw in the Style Guide for Python Code (PEP8).

Documentation Standards

Documentation Standards refers to how programs are identified and commented. Documentation can make the difference between an elegant, easily-understood piece of code and a confusing mass of commands. Some languages, such as C, were originally designed with no documentation standard other than a commenting syntax. Others, such as Java, have a well-developed mechanism for defining comments and generating documentation. Python is more like C than Java in this regard, although there are third-party tools available for documentation generation. A documentation style is normally defined by the organization you are programming for. For CP104, our documentation style requirements are defined below.

Python comments lines begin with a # sign and go to the end of the line. A comment may appear by itself on a line or may appear at the end of a line after a piece of Python code. The latter is called an end-line comment and the comment must be the last thing on the line, i.e. code cannot follow a comment on a line. For typical Python code use end-line comments sparingly.

      
# this entire lime is a comment and no code can appear on this line
python code    # this is an end-line comment

Example

      
# Calculate and display the size of a rectangle.
size = width * height     # size in m^2.
print(f"The square size is {size} meters squared.")

Code frequently requires a number of consecutive lines of documentation to identify the author of the code or describe the overall purpose of the code. Languages typically have an alternate method for identifying multiline comments. In Python, multiline comments, referred to as document strings, begin and end with three quotes (single or double - they must be consistent for a comment) . Everything between the opening and closing sets of quotes is considered non-program text.

Example

      
"""
-------------------------------------------------------
Program to calculate the 2-dimensional size of a rectangle.
-------------------------------------------------------
Author:  David Brown
Id:
Email:   dbrown@wlu.ca
__updated__ = "2023-05-04"
-------------------------------------------------------
"""

(__updated__ is a special code recognized by PyDev that updates its date whenever the file containing it is saved. Thus it can automatically keep track of the last time you edited a program.)

For CP104 we require comprehensive documentation that identifies you as an author and clearly demonstrates your understanding of both the problem you are trying to solve and your solution. The following template lists the elements of your programs and functions that you must comment. Note that some of these program sections and comments do not apply to the types of programs you are writing now, but they will later in the term. (For example, functions without parameters do not have a Parameters section.) We will build up this template as the term progresses as new language features are introduced.

Use the appropriate sections of this template for all your programming. Note that the square brackets are there just to show you the elements you are to fill in - they should not appear in your actual documentation. Any items with brace brackets, i.e. {}, will be executed and filled in as appropriate by the Eclipse / PyDev environment.

      
"""
-------------------------------------------------------
[Program Description]
-------------------------------------------------------
Author:  [your name]
ID:      [your student ID]
Email:   [your Laurier email address]
__updated__ = "${isodate}"
-------------------------------------------------------
"""
# Imports

# Constants

def [function definition]:
    """
    -------------------------------------------------------
    [Function Description]
    -------------------------------------------------------
    Parameters:
       [parameter name - parameter description (parameter type and constraints)]
    Returns:
       [return value name - return value description (return value type)]
    -------------------------------------------------------
    """

    [other comments as necessary]

You must fill in the following elements in the template:

[Program Description]

Brief description of the program. The description should be sufficiently clear and complete so that a reader would not require to see the original problem statement to understand what you are doing.

[your name] / [your student ID] / [your Laurier email address]

Standard identification information. Note that the date field will automatically fill in under Eclipse / PyDev.

# Imports

The Python code for importing external libraries goes after this comment.

# Constants

Any constants go after this comment.

[function definition]

The Python code for the function header.

[Function Description]

A concise, but clear description of what the function does. Describe the function parameters, if any.

[parameter name - parameter description (parameter type and constraints)]

The three-part format for each function parameter. What has to be true about the parameter for the function to work correctly? Use the Python keywords for the type, i.e. int, float, str. (Use None if the function does not return anything.) Example:

          
    """
    …
    Parameters:
        radius - radius of a circle (float > 0)
    …
    """

[return value name - return value description (return value type)]

The three-part format for the return values for the function. What are the function's return values when the function ends? Use returns: or prints: as appropriate. Use the Python keywords for the type, i.e. int, float, str. Example:

          
    """
    …
    Returns:
        diam - diameter of the circle (float)
    …
    """

[other comments as necessary]

These are further comments that help someone looking at the program understand how it works.

If any of these elements are missing, leave the matching comments out as well. Comment sections should be repeated as necessary: for example, each function in your code requires its own function documentation section.