← VCE Applied Computing U1O2

Purposes of internal documentation

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

Part of: VCE Applied Computing U1O2 Programming: Naming conventions and internal documentation — Module 6, QCE Digital Solutions Unit 1 — Algorithms and Programming Techniques — Module 95, QCE Digital Solutions Unit 1 — Programmed Solutions — Module 119, QCE Digital Solutions Unit 4 — Complex Digital Data Exchange Problems and Solution Requirements — Module 137, QCE Digital Solutions Unit 4 — Prototype Digital Data Exchanges — Module 133

Understanding Purposes of internal documentation in VCE Applied Computing U1O2

What it does: This comment gives the reason behind the value 50. A maintainer can then update it safely if the policy changes. Internal documentation is explanation written inside the code. It does not change how fast the program runs. Clear explanations make errors easier to find and updates easier to make, but testing is still needed. Without explanations, a new programmer must work out the purpose of every section by guessing. Comments are ignored by the interpreter or compiler, so they only help human readers. Even the original programmer forgets details over time, so internal documentation helps them too. Good internal documentation explains purpose, for example: # GST rate used to calculate the price.

Common mistakes: 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. 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.

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 to a class →

This module's key terms are also in a printable crossword (Modules 8–88) and word search (Modules 8–124).

Take this worksheet further — free with Cloodit

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

Learning
Duo
What is the main purpose of internal documentation?
To explain inside the code what it does and whyTo make the program run faster
Matches
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.
Applying
Meanings
Term
internal documentation
Meaning
Explanation written inside the code to say what it does and why, so other programmers can understand, fix and update it later.
Practice
price = 40.00
Testing
Gaps
Add 10% GST so the total is correct
Check Answer
Spots
3gst_rate = 0.10
4gst = price + gst_rate

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

The 'Hippopotamus' badge — Savannah Titan, one of Cloodit's 106 collectible badges
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. 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
Internal documentation is explanation written inside the code. It does not change how fast the program runs.
2. Where is internal documentation written?
A. In a separate user manual only
B. Inside the source code, such as in comments ✓
Internal documentation sits within the code itself. A separate user manual is external documentation.
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 ✓
Internal documentation helps programmers, including your future self, understand the code. End users do not see it.
4. Which comment best explains WHY the code does something?
A. # Round up so the customer is never undercharged ✓
B. # Round the number
A good comment gives the reason behind the code, not just a restatement of what the code already shows.
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
Clear explanations make errors easier to find and updates easier to make, but testing is still needed.

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.

Key Term

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

Fill in the Blanks

1. price = 50 # Add 10% GST so the total is correct total = price * 1.1
Hint: Type the symbol that starts a single-line comment in Python
2. def add_gst(price): """Return the price including GST.""" return price * 1.1
Hint: Type the keyword that defines a function, which the docstring then explains
3. # Why: GST is 10% in Australia rate = 0.1 total = price + price * rate
Hint: Type the arithmetic operator that multiplies the price by the rate the comment explains
4. # Helps future programmers fix this code def double(n): return n * 2
Hint: Type the keyword that sends a value back from the function
5. # Show the final mark to the student print(mark) # Maintenance: edit here to change format
Hint: Type the function that displays output on the screen

Spot the 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)
Line 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.
Question 2
A score = 5 - 8
B Stop score going below 0
C if score < 0:
D score = 0
Line 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.
Question 3
A def area(w, h):
B result = w * h
C // width times height
D return result
Line C — Python comments start with #, not //. The line should be: # width times height.
Question 4
A # Player starts with 5 lives
B lives = 3
C lives = lives - 1
D print(lives)
Line 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.
Question 5
A def add(a, b):
B """Add two numbers
C and return the sum.
D return a + b
Line 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.

Student with a class code? Join your class →