1. No Personal Information

Do not include any personal information, such as your name or MSU PID, in any of your source code files. All project solutions are sent off campus to a software system which compares source code files for similarities.

2. Source Code Format

Source code lines will be no more than 120 characters long. Break long lines into multiple shorter lines using the continuation character ("\").

Only one statement will be included on a given line of the source code.

Use four spaces for indentation.

Blank lines and spaces will be used to enhance the readability of both source statements and comments.

All import statements will appear after the source code header and before any other Python code in the program.

All function definitions will appear after the import statements and before any other Python code in the program.

3. Source Code Header

Main source code file will contain an introductory block of comments that identifies the assignment and gives a brief overview of the program. For example:

###########################################################
#  Computer Project #5
#
#  Algorithm
#    prompt for an integer
#    input an integer
#    loop while not end-of-data
#       call function to count number of digits in integer
#       output the number of digits
#       prompt for an integer
#       input an integer
#    display closing message
###########################################################

      

4. Descriptive Comments

The source code will include comments that describe the functionality of significant blocks of code. Comments are particularly important before all blocks of code that perform major data manipulations or error processing.

For readability, each comment will be indented at the same level as the block of code that it describes or, if it fits within the 120-character limit and describes just a single line of code, to the right of that line.

See Section 3.3.1 Readability in the text starting on page 167.

Place Comments to Indicate:

• The purpose of objects that are not clear from their names.
• Where something is "tricky", "clever", or "unusual"; if it required thought on your part, it should be commented.
• If it was hard to write, it is probably hard to read. Add a comment.

# Calculate the total sum of a list of numbers.
# This loop iterates through each number in the list and adds it to the total.

numbers = [10, 20, 30, 40, 50]
total = 0  # Initialize the total sum to 0

for number in numbers:
    total += number  # Add the current number to the total

print(f"The total sum is: {total}")

5. Mnemonic Identifiers

Meaningful identifiers taken from the problem domain will be used for all names. Furthermore, a name will be used for only one purpose (the same name will not be used for more than one purpose).

Mnemonic identifiers are variable, function, or class names that are meaningful and descriptive, making the purpose of the code easier to understand. They help both the original programmer and others who read the code later. Here's an example:

Non-Mnemonic Identifiers (Bad Practice):

In this example, the variables x, y, and z provide no context about their purpose.

x = 50
y = 30
z = x * y  # What do x, y, and z represent?
print(z)
    

Mnemonic Identifiers (Good Practice):

length, width, and area are meaningful names that immediately indicate their purpose.

Comments provide additional context but aren't necessary to understand the code because the identifiers are self-explanatory.

# Calculate the area of a rectangle
length = 50  # Length of the rectangle in meters
width = 30   # Width of the rectangle in meters
area = length * width  # Area is calculated as length multiplied by width

print(f"The area of the rectangle is: {area} square meters")
    

6. Symbolic Constants

Symbolic constants will be used instead of embedding arbitrary numeric and character constants in the source code. Use "upper with under" style for all symbolic constants:

HEAT_OF_FUSION = 79.71  # Calories to melt one gram of ice
    

7. Variable and Function Names

Use "lower with under" style for all variable and function names. In some situations, it is appropriate to append type information to variable names as a visual reminder about the purpose of those variables:

student_count = 0         # Number of students in class

fahrenheit_float = 0.0    # Temperature in Fahrenheit
    

8. Function and Class Method Headers

Using docstrings (delimited by triple double-quotes), each function should contain an introductory block of comments that explains:

• The purpose of the function.
• The parameters passed to the function and their types.
• The data modified by the function.
• The value(s) returned by the function.
• Any assumptions required for the function to work correctly.

Here are some examples:

def count_digits( value ):
    """
    Count the number of digits in an integer value.

    value:  The value to be processed (int)
    Returns:  The number of digits in value (int)
    """

def add_assignment( grade_book, possible_pts ):
    """
    Adds a new assignment to a grade book.

    grade_book: the grade book (dict)
      maps assignment names (str) to grade dicts,
         where a grade dict maps student PIDS (str)
         to grades (float)
      grade_book is both read and modified

    possible_pts: the total points possible,
      must be positive
    """
    

9. Class Names

Use "CamelCase" style for all class names. CamelCase capitalizes the first letter of each word and does not include underscores. Here are some examples:

class SalariedEmployee:
    pass

class HourlyEmployee:
    pass