This document outlines the expectations of code organization and style for CptS 111.
Source files (.py files) should have a name that describes your program. For example, a Python program to compute the area of various shapes could be called area.py instead of a non-informative name, such as program.py. For labs, it is recommended you name your python files for each task, e.g. lab1task1.py. For programming assignments, the assignment specification will state what to name your source file.
Input/output files (e.g. .txt files, .csv files, etc.) should have a name that describes the content of the file.
Variables, functions, and classes should be named informatively. For example, do not name a variable, variable. The name should describe the value of the variable (i.e. radius for storing the radius of a circle), computation performed by the function (i.e. compute_circumference() to compute the circumference of a circle), or the semantics of the class (i.e. Circle to represent information and functionality related to circles). Thoughtful identifier names improves the readability of your code to yourself and others.
Liberally comment your code! It helps you and others who may read your code. Also, should you use an algorithm, idea, or any other content that is not your own, use comments in your code to properly cite your sources.
To describe the purpose of a line of code, it is beneficial to place comments throughout your code, not just when defining functions and objects.
Begin programs with a header section that indicates
For example:
##############################################
# Programmer: Gina Sprint
# Class: CptS 111-01, Spring 2017
# Programming Assignment #1
# 8/24/16
#
# Description: This program computes...
# No sources to cite.
##############################################
# Programmer: Gina Sprint
# Class: CptS 111-01, Spring 2017
# Programming Assignment #1
# 8/24/16
#
# Description: This program computes...
# No sources to cite.
'''
Programmer: Gina Sprint
Class: CptS 111-01, Spring 2017
Programming Assignment #1
8/24/16
Description: This program computes...
No sources to cite.
'''
Every function (and method) should contain a docstring, a comment placed immediately under the function header. Docstrings appear when you use the help() function with a function. The docstring should describe the function, function parameters, and the result if the function returns a value.
For example:
def compute_area_circle(radius):
'''
Computes the area of a circle by multiplying PI by the square of the circle's radius
Parameter radius: radius of the circle whose area this function computes
Returns: area of a circle
'''
area = 3.14 * radius ** 2
return area
help(compute_area_circle)
print(compute_area_circle(2.0))
Insert blank space before and after commas and operators such as +, =, *, /, //