Purposes of internal documentation: code maintenance
Name:
Date:
Class:
A
Quick Questions
Shade in the A or B circle for each question.
1. Why do programmers add internal documentation such as comments to their code?
2. Which is a header comment with purpose, author and date?
3. Where should a header comment normally be placed?
4. Which comment best documents a function?
5. A programmer changes a function so it now returns a rounded value, but leaves the old comment saying it returns an exact value. What is the problem?
B
Match the Pairs
Draw a line connecting each item on the left to its match on the right.
| Left column | Right column | |
|---|---|---|
| 1# Purpose: Calculate canteen order totals # Author: J. Tran Date: 2025-03-14 | AA comment kept up to date after a change, so the documentation still matches what the code does | |
| 2# Updated 2025-05-02: tax now 10% (was 8%) | B# Author: A. Patel print("Welcome") | |
| 3A comment above a function explains what it does, so another programmer can change it safely | C# Returns the total cost including GST def total_cost(price): | |
| 4Internal documentation sits inside the source code, next to the code it describes | DThe comments only repeat the code and give no purpose. Better comments would explain why, for example that 0.1 is the discount rate. | |
| 5# Returns the average mark def get_total(marks): return sum(marks) | EThe comment is out of date. It says average but the function returns the total, so it misleads the next programmer. Update the comment or the code so they match. | |
| 6x = 0.1 # sets x to 0.1 y = x * 5 # multiplies x by 5 | FA header comment stating the program's purpose, author and date so a maintainer knows what the file is for and who wrote it |
C
Definitions
internal documentation
D
Fill in the Blanks
Complete each line of code by filling in the missing parts.
1.
top = 100 _ highest mark possible in the test
2.
# Purpose: track student marks
# ______: J. Nguyen
# Date: 12/03/2025
3.
# Calculate the area of a rectangle
___ area(w, h):
return w * h
4.
# Add 10% GST to the price
total = price * ___
5.
# _______: Store and total student marks
# Author: J. Nguyen
# Date: 12/03/2025
E
Spot the Error
Shade in the letter of the line that contains an error.
Question 1
A
# Purpose: add up cart prices
B
# Author: J Lee, 2025-03-02
C
def total(prices):
D
// Add all prices together
E
return sum(prices)
Question 2
A
Purpose: convert temps
B
# Author: M Chen, 2025-05-14
C
def to_f(c):
D
return c * 9 / 5 + 32
Question 3
A
# Purpose: manage login limits
B
# Author: A Smith, 2025-06-01
C
MAX_USERS = 50 # 20 users max
D
print(MAX_USERS)
Question 4
A
# Purpose: shape calculations
B
# Returns rectangle perimeter
C
def area(w, h):
D
return w * h
Question 5
A
# Purpose: grade a mark
B
def grade(mark):
C
# does stuff
D
return mark >= 50
Answer Key
Purposes of internal documentation: code maintenance
Section A: Quick Questions
Q1
A — So another programmer, or you later, can understand and safely change the program
Q2
B — # Purpose: Calculate GST on a sale | Author: J. Chen | Date: 12/03/2025
Q3
A — At the top of the program file
Q4
B — # Returns the total price including GST for a given price
Q5
A — The comment is out of date and could mislead the next programmer
Section B: Match the Pairs
Q1
# Purpose: Calculate canteen order totals
# Author: J. Tran Date: 2025-03-14 → A header comment stating the program's purpose, author and date so a maintainer knows what the file is for and who wrote it
Q2
# Updated 2025-05-02: tax now 10% (was 8%) → A comment kept up to date after a change, so the documentation still matches what the code does
Q3
A comment above a function explains what it does, so another programmer can change it safely → # Returns the total cost including GST
def total_cost(price):
Q4
Internal documentation sits inside the source code, next to the code it describes → # Author: A. Patel
print("Welcome")
Q5
# Returns the average mark
def get_total(marks):
return sum(marks) → The comment is out of date. It says average but the function returns the total, so it misleads the next programmer. Update the comment or the code so they match.
Q6
x = 0.1 # sets x to 0.1
y = x * 5 # multiplies x by 5 → The comments only repeat the code and give no purpose. Better comments would explain why, for example that 0.1 is the discount rate.
Section C: Definitions
Q1
internal documentation — Comments inside the code, like a header with purpose, author and date, and notes on each function, that help others (or you later) understand and safely change the program.Section D: Fill in the Blanks
Q1
top = 100 # highest mark possible in the testQ2
# Purpose: track student marks
# Author: J. Nguyen
# Date: 12/03/2025Q3
# Calculate the area of a rectangle
def area(w, h):
return w * hQ4
# Add 10% GST to the price
total = price * 1.1Q5
# Purpose: Store and total student marks
# Author: J. Nguyen
# Date: 12/03/2025Section E: Spot the Error
Q1
D — Python comments start with #, not //. The // line is not a comment and causes a syntax error. It should be '# Add all prices together'.
Q2
A — The header comment is missing its # so Python reads it as code and raises a syntax error. It should be '# Purpose: convert temps'.
Q3
C — The comment says 20 but the value is 50. Out-of-date comments mislead the next programmer. Keep comments up to date: '# 50 users max'.
Q4
B — The function comment says perimeter but the function returns w * h, which is the area. A wrong function comment misleads maintainers. It should say '# Returns rectangle area'.
Q5
C — A vague comment like 'does stuff' gives the next programmer no useful information. The comment should explain the 50 in the code, such as '# Pass mark is 50'.