Comments

Documenting you source code is very important. In the real world, programs are maintained by many different people other than their original creators. Comments are used primarily to state what the code is doing, while the code itself describes how you are doing it.

File Prolog
Class Prolog
Method Prolog
Function Prolog
Inline Comments
Sidebar Comments

Note

All comments in your Python programs are to be specified using the hash (#) symbol notation, unless otherwise indicated.

File Prolog

Every module or program file must contain a header or prolog used to describe the contents of the file. An example file header is shown below: (Note: leave at least one blank after the header and before the first statement or declaration.)

# hello.py
#
# created by: R. Necaise
# modified by: John Smith
# section: 01
#
# Implements the classic 'Hello World!!' program in python. If the description
# requires multiple lines, then it should use as many lines as necessary, with
# line beginning with a hash symbol.

The file header should include the following information:

The name of the source file.
Your name:
- If you are creating an original source file for which you are the author of the entire contents, include your name as having created the source code.
- If you modify a source file originally created by someone else, then include both your name as having modified the file and the name of the author who created the original file.
Your section number.
A description of the file.
- For a driver or program file, the description should provide an overview of the complete program.
- For modules that define and implement one or moreADTs, the description should briefly describe all of the AD Ts contained in the module or state the overall purpose of the AD Ts.

In addition, you can use dashes, hashes, or asterisks to set off the file header if you wish. For example, we could rewrite the previous comment as

# -----------------------------------------------------------------------------
# bag.py
#
# created by: R. Necaise
# section: 01
#
# Implements the simple Bag ADT using a Python list.
# -----------------------------------------------------------------------------

Class Prolog

The class prolog is a brief comment that describes or explains the purpose of the class. It should appear just before the definition of the class. You may leave a blank line between the comment and class definition, but it's not required.

# Defines a point in the 2-D Cartesian coordinate system. The points can
# be either integers or floating-point values.

class Point :

In addition, you can set off the comment with dashes, hashes, or asterisks if you wish. For example, we could rewrite the previous comment as

# -----------------------------------------------------------------------
# Defines a point in the 2-D Cartesian coordinate system. The points can
# be either integers or floating-point values.
# -----------------------------------------------------------------------

class Point :

Method Prolog

As with a class prolog, the method prolog is a brief comment that describes or explains the purpose of the method. It should appear just before the method definition and it should be indented at least one space more than the method header.

class Point :
# Returns the x coordinate of the point.
def getX( self ):
return self._xCoord

# Returns the y coordinate of the point.
def getY( self ):
return self._yCoord

The method prolog should be brief but include the following information:

Purpose: what the method does. If the method modifies the object, indicate how it's modified.
Arguments: how the arguments, if there are any, will be used.
Preconditions: state the preconditions for the object itself (i.e. can not be empty) and/or the arguments.
Output: is there a return value? If so, indicate what is returned.

Function Prolog

A function prolog is very similar to a method prolog. It is a brief comment that describes or explains the purpose of the function and its arguments. The function prolog, which should appear just before the function definition, should be indented at least one space more than the function header and include the same information as indicated for method prologs.

# Prompts and extracts the user for the number of tosses.
def extractNumTosses():
:
:

Inline Comments

Inline comments explain a block of code. Such a comment should precede the code itself and should be indented at least one space more than the block it describes. A blank line should be placed before the inline comment, and after the block of code to separate it from the next block or statement. (Note: the use of the term 'block of code' in this instance refers to any group of statements.)

# Prompt and extract the student's first and last name.
firstName = input( "Enter student's first name: " )
lastName = input( "Enter student's last name: " )

# Construct and print the fullname.
fullName = lastName + ", " + firstName.
print( "Full name is:", fullName )

Sidebar Comments

A sidebar comment is one which explains a single statement and should follow the statement on the same line. The comment should be brief, accurate and precise.

# Iterates over a string and counts the number of uppercase
# and lowercase characters encountered.
numLower = 0
numUpper = 0
for letter in theString :
if letter >= "A" and letter <= "Z" : # is letter uppercase?
numUpper += 1
elif letter >= "a" and letter <= "z" : # is letter lowercase?

Note

In-line and sidebar comments should be used sparingly. Before adding such comments, you should first attempt to make the code itself more understandable by using meaningful identifier names, replacing groups of statements with function or helper method calls, or reducing the complexity of the code.

Naming Conventions

Python Style Guide

Readability