Commenting your code

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, Fall 2019
 *
 * 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

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