← VCE Software Development U3O1

Purposes of internal documentation: code maintenance

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.

Part of: VCE Software Development - U3O1 - Programming — Module 53, VCE Software Development - U4O1 - development and evaluation — Module 106, QCE Digital Solutions Unit 3 — Real-World Problems and Solution Requirements — Module 52, WA Computer Science ATAR Year 11 — Pseudocode and Algorithm Design — Module 97, WA Computer Science ATAR Year 11 — Modular Programming — Module 41

Understanding Purposes of internal documentation: code maintenance in VCE Software Development U3O1

What it does: A function comment describes the function's job. The maintainer can understand it without reading every line. Internal documentation is written as comments within the code file itself, not in a separate manual. A header comment at the top of a file states why the program exists, who wrote it and when. A vague comment tells a maintainer nothing. The header goes at the top so anyone opening the file sees the purpose, author and date straight away. A function comment should explain what the function does, and what it takes in and gives back. One word like 'function' adds no help.

Common mistakes: Python comments start with #, not //. The // line is not a comment and causes a syntax error. It should be '# Add all prices together'. The header comment is missing its # so Python reads it as code and raises a syntax error. It should be '# Purpose: convert temps'.

Class: _____________________ · Name: _____________________ · Date: _________

Free printable worksheet with full answer key — or add this module to a class and your students practise it interactively.

🖨 Print worksheet + answer key Add Purposes of internal documentation: code maintenance to a class →

This module's key terms are also in a printable crossword (Modules 48–71) and word search (Modules 10–71).

Take this worksheet further — free with Cloodit

Each concept is reinforced from every angle — learned, then applied, then tested.

Learning

Duo

Why do programmers add internal documentation such as comments to their code?

So another programmer, or you later, can understand and safely change the programSo the program runs faster

Matches

# 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.

Applying

Meanings

Term

internal documentation

Meaning

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.

Practice

def calc_gst(price):

Testing

Gaps

top = 100 highest mark possible in the test

Check Answer

Spots

3def total(prices):

4 // Add all prices together

Cloodit turns curriculum-aligned coding content into journeys students work through one biome at a time.

Students earn collectable badges

Over 100 of them, across seven natural biomes.

Study Buddy

Students build a real study resource

Turns their work into revision material ready for Flash Cards and Exam study.

Diamond Dash — one of Cloodit's live, competitive Sprint games

Students lock in with Sprints

Live, competitive practice for the start of the lesson or a teacher-led lesson finisher.

A Cloodit certificate of achievement, ready to personalise and print

Custom printable certificates

Honour your top performers, or encourage a student who's trying hard — ready to print in seconds.

Add to class →

Quick Questions

1. Why do programmers add internal documentation such as comments to their code?

A. So another programmer, or you later, can understand and safely change the program ✓

B. So the program runs faster

Internal documentation supports code maintenance. Comments are ignored when the program runs, so they do not change speed.

2. Which is a header comment with purpose, author and date?

A. # This is a comment

B. # Purpose: Calculate GST on a sale | Author: J. Chen | Date: 12/03/2025 ✓

A header comment at the top of a file states why the program exists, who wrote it and when. A vague comment tells a maintainer nothing.

3. Where should a header comment normally be placed?

A. At the top of the program file ✓

B. Buried at the end of the last function

The header goes at the top so anyone opening the file sees the purpose, author and date straight away.

4. Which comment best documents a function?

A. # function

B. # Returns the total price including GST for a given price ✓

A function comment should explain what the function does, and what it takes in and gives back. One word like 'function' adds no help.

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?

A. The comment is out of date and could mislead the next programmer ✓

B. There is no problem because comments are ignored by Python

Python ignores comments, but people do not. An outdated comment can cause a maintainer to make wrong changes, so comments must be kept up to date.

Match the Pairs

# 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

# 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

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):

Internal documentation sits inside the source code, next to the code it describes → # Author: A. Patel print("Welcome")

# 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.

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.

Key Term

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.

Fill in the Blanks

1. top = 100 # highest mark possible in the test

Hint: Type the symbol that starts a comment so Python ignores the rest of the line.

2. # Purpose: track student marks # Author: J. Nguyen # Date: 12/03/2025

Hint: Type the header label that tells a later programmer who wrote the program.

3. # Calculate the area of a rectangle def area(w, h): return w * h

Hint: Type the keyword that defines the function the comment above describes.

4. # Add 10% GST to the price total = price * 1.1

Hint: Type the multiplier that makes the code match what its comment says, so the comment stays accurate.

5. # Purpose: Store and total student marks # Author: J. Nguyen # Date: 12/03/2025

Hint: Type the header label that explains why the program exists.

Spot the 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)

Line D — Python comments start with #, not //. The // line is not a comment and causes a syntax error. It should be '# Add all prices together'.

Question 2

A Purpose: convert temps

B # Author: M Chen, 2025-05-14

C def to_f(c):

D return c * 9 / 5 + 32

Line A — The header comment is missing its # so Python reads it as code and raises a syntax error. It should be '# Purpose: convert temps'.

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)

Line 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'.

Question 4

A # Purpose: shape calculations

B # Returns rectangle perimeter

C def area(w, h):

D return w * h

Line 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'.

Question 5

A # Purpose: grade a mark

B def grade(mark):

C # does stuff

D return mark >= 50

Line 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'.

Student with a class code? Join your class →