CS 141: Coding Style

Just like when writing in English, using good style when writing in a programming language is important because it helps you and other people read your code. Easily-readable code is important for you so you can maintain it (update it later), and for other people so they can figure out what it does as easily as possible, and possibly change it.

Comments

Commenting your code is an important part of the software development process. It is critical to document a piece of code, be it a line, a few lines, or a longer section, with a comment that explains everything necessary to understand the code that is not immediately obvious by reading it. In other words, if there is any doubt in your mind about whether a section of code requires a comment, then comment it.

Comments are used to explain code to someone reading your program. That means that a comment like this

num_users = 30   # This code sets the number of users to 30.

is not particularly useful. The comment is redundant because someone reading your code can tell that the variable num_users is being set to 30 from the line of code. Instead, if this is an important line of code, explain why the variable is being set to 30.

Think of comments as explaining to a reader or user what your program is doing.

How much should I comment?

You should include a comment at the top of the whole program (see below) and immediately before each function definition (see below). You should also include comments at other critical points in your program where you feel the code warrants further explanation. Err on the side of commenting too much, rather than too little.

Comments at the top of your program

Every program you write should have the following information at the top in a comment:

'''
 * Program or Lab #: Insert assignment name
 *
 * Programmer: Insert your name
 *
 * Due Date: Insert due date
 *
 * COMP141, Spring 2020
 *
 * Pledge: I have neither given nor received unauthorized aid
 *         on this program. 
 *
 * Description: Insert a brief paragraph describing the program
 *
 * Input: Insert a brief description of user inputs, or "None" if
 *        there is no user input
 *
 * Output: Insert a brief description of the program output
 *
'''

Note: You can copy and paste the comment lines shown here to the top of your assignment each time. You will need to make the appropriate changes for each assignment (assignment number, assignment name, due date, description, input, and output).

Comments before each function

(This section is only applicable for Project 3 and after. Projects 1 and 2 do not use functions.)

Every function (other than main) must have a comment immediately before its definition. You should include the following information:

A description of what the function does.
For each parameter: a description of what the parameter means or controls.
If the function returns a value, a description of what the return value is.

For example, this might look like:

	# This function computes the circumference of a circle.
	# Parameters: r, the radius of the circle.
	# Returns: the circumference of the circle.
	def circumference_of_circle(r):
		return 2 * 3.14 * r