Purposes of internal documentation

Name:

Date:

Class:

Quick Questions

Shade in the A or B circle for each question.

1. What is the main purpose of internal documentation?

A To explain inside the code what it does and why

B To make the program run faster

2. Where is internal documentation written?

A In a separate user manual only

B Inside the source code, such as in comments

3. Who is internal documentation mainly written for?

A End users who only run the program

B Future programmers who read and maintain the code

4. Which comment best explains WHY the code does something?

A # Round up so the customer is never undercharged

B # Round the number

5. How does internal documentation support code maintenance?

A It helps programmers find, fix and update code more quickly

B It removes the need to test the code after changes

Match the Pairs

Draw a line connecting each item on the left to its match on the right.

Left column		Right column
1# Skip students with no marks		A# Pass mark is 50 because the school policy says so
2"""Return the average of a list of marks."""		BA comment that explains why the next lines of code are there
3Internal documentation explains why code was written, which helps a future programmer maintain it		CThe comment only repeats the code. It does not explain what x is or why it has this value, so it does not help a future programmer.
4Internal documentation supports maintenance by stating who made changes and what the file is for		DA docstring that describes what a function does for future programmers
5x = 0.1 # sets x to 0.1		E# Author: J. Lee Purpose: Calculate house points
6total = total * 1.1 # Add GST # (code later changed to 1.15, comment not updated)		FThe comment is out of date and no longer matches the code, which misleads the programmer who maintains it.

Definitions

internal documentation

Fill in the Blanks

Complete each line of code by filling in the missing parts.

price = 50 _ Add 10% GST so the total is correct total = price * 1.1

___ add_gst(price): """Return the price including GST.""" return price * 1.1

# Why: GST is 10% in Australia rate = 0.1 total = price + price _ rate

# Helps future programmers fix this code def double(n): ______ n * 2

# Show the final mark to the student _____(mark) # Maintenance: edit here to change format

Spot the Error

Shade in the letter of the line that contains an error.

Question 1

A # Calculate GST for a price

B price = 50

C gst_rate = 0.10

D gst = price + gst_rate

E print(gst)

Question 2

A score = 5 - 8

B Stop score going below 0

C if score < 0:

D score = 0

Question 3

A def area(w, h):

B result = w * h

C // width times height

D return result

Question 4

A # Player starts with 5 lives

B lives = 3

C lives = lives - 1

D print(lives)

Question 5

A def add(a, b):

B """Add two numbers

C and return the sum.

D return a + b

Answer Key

Purposes of internal documentation

Section A: Quick Questions

A — To explain inside the code what it does and why

B — Inside the source code, such as in comments

B — Future programmers who read and maintain the code

A — # Round up so the customer is never undercharged

A — It helps programmers find, fix and update code more quickly

Section B: Match the Pairs

# Skip students with no marks → A comment that explains why the next lines of code are there

"""Return the average of a list of marks.""" → A docstring that describes what a function does for future programmers

Internal documentation explains why code was written, which helps a future programmer maintain it → # Pass mark is 50 because the school policy says so

Internal documentation supports maintenance by stating who made changes and what the file is for → # Author: J. Lee Purpose: Calculate house points

x = 0.1 # sets x to 0.1 → The comment only repeats the code. It does not explain what x is or why it has this value, so it does not help a future programmer.

total = total * 1.1 # Add GST # (code later changed to 1.15, comment not updated) → The comment is out of date and no longer matches the code, which misleads the programmer who maintains it.

Section C: Definitions

internal documentation — Explanation written inside the code to say what it does and why, so other programmers can understand, fix and update it later.

Section D: Fill in the Blanks

price = 50
# Add 10% GST so the total is correct
total = price * 1.1

def add_gst(price):
    """Return the price including GST."""
    return price * 1.1

# Why: GST is 10% in Australia
rate = 0.1
total = price + price * rate

# Helps future programmers fix this code
def double(n):
    return n * 2

# Show the final mark to the student
print(mark)
# Maintenance: edit here to change format

Section E: Spot the Error

D — The comment says the code calculates GST, but adding the rate to the price does not do that. It should multiply: gst = price * gst_rate. Comments must match what the code does.

B — The comment has no # at the start, so Python reads it as code and gives an error. It should be: # Stop score going below 0.

C — Python comments start with #, not //. The line should be: # width times height.

A — The comment says 5 lives but the code sets lives = 3. A comment that does not match the code misleads future programmers. It should say 3 lives.

C — The docstring was opened with triple quotes but is never closed, which causes a syntax error. The line should end with the closing triple quotes.