← WA Computer Science ATAR Unit 1

Internal versus external program documentation

Internal documentation is inside the code (comments, docstrings). External is separate, like a user guide or technical document covering each module's purpose, inputs and outputs.

Part of: WA Computer Science ATAR Year 11 — Modular Programming — Module 72

Understanding Internal versus external program documentation in WA Computer Science ATAR Unit 1

What it does: A docstring is stored inside the function itself, so it is internal documentation of the function's purpose. A separate technical document records each module's purpose, inputs and outputs so developers can maintain the program without reading every line. A user guide is a separate document, not part of the code, so it is external documentation. User documentation shows how to install and use the program. Technical documentation is aimed at programmers.

Common mistakes: The docstring says the function returns the area, but this line calculates the perimeter. Internal documentation must match what the code does. It should be return w * h. The docstring is closed with only two quotation marks, so Python sees an unfinished string and gives a syntax error. A docstring must end with three quotation marks.

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 Internal versus external program documentation to a class →

This module's key terms are also in a printable crossword (Modules 100–314) and word search (Modules 100–470).

Take this worksheet further — free with Cloodit

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

Learning
Duo
A comment written above a function in the .py file is which type of documentation?
Internal documentationExternal documentation
Matches
A user guide is internal documentation because it explains how the program works
↓
A user guide is external documentation, not internal. It is a separate document and is not written inside the code.
Applying
Meanings
Term
internal vs external documentation
Meaning
Internal documentation is inside the code (comments, docstrings). External is separate, like a user guide or technical document covering each module's purpose, inputs and outputs.
Practice
def average(marks):
Testing
Gaps
Internal documentation: stays in the code
Check Answer
Spots
2 """Return the area."""
3 return 2 * (w + h)

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

The 'Butterfly' badge — Branch Hopper, 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. A comment written above a function in the .py file is which type of documentation?
A. Internal documentation ✓
B. External documentation
Internal documentation lives inside the code itself. Comments and docstrings are both internal.
2. A separate user guide explaining how to run a program is which type of documentation?
A. External documentation ✓
B. Internal documentation
A user guide is a separate document, not part of the code, so it is external documentation.
3. Who is user documentation mainly written for?
A. People who use the program ✓
B. Programmers who maintain the code
User documentation shows how to install and use the program. Technical documentation is aimed at programmers.
4. Which document is written for the programmers who must maintain the program?
A. User documentation
B. Technical documentation ✓
Technical documentation describes how the program and its modules work, so developers can fix or extend it.
5. Which of these is an example of internal documentation?
A. A PDF user manual
B. A docstring inside a function ✓
A docstring is written in the code. A PDF manual is a separate file, so it is external.

Match the Pairs

# Convert marks to a percentage → Internal documentation: a comment written inside the code to explain what it does
User guide: Click Save to store your marks → External documentation: a separate document that tells users how to operate the program
Internal documentation describes a function's purpose, inputs and output from inside the code → """Return the average of a list of marks."""
Technical documentation is external and lists each module's purpose, inputs and outputs for maintainers → Module: grades.py | Input: marks list | Output: average
A user guide is internal documentation because it explains how the program works → A user guide is external documentation, not internal. It is a separate document and is not written inside the code.
Technical documentation is for end users who have never seen the code → Technical documentation is written for developers and maintainers. End users need the user documentation instead.

Key Term

internal vs external documentation
Internal documentation is inside the code (comments, docstrings). External is separate, like a user guide or technical document covering each module's purpose, inputs and outputs.

Fill in the Blanks

1. # Internal documentation: stays in the code
Hint: Type the symbol that starts a single-line Python comment, which is internal documentation.
2. def area(w, h): """Return the area of a rectangle.""" return w * h
Hint: Type the keyword that defines a function, whose docstring is internal documentation.
3. def area(w, h): """Return the area of a rectangle.""" print(area.__doc__)
Hint: Type the special attribute name that holds a function's docstring.
4. def internal(doc): return doc in ("comment", "docstring")
Hint: Type the operator that checks whether a value is a member of a tuple.
5. docs = ["user guide", "technical document"] for d in docs: print(d)
Hint: Type the keyword that loops through each external document in the list.

Spot the Error

Question 1
A def area(w, h):
B """Return the area."""
C return 2 * (w + h)
Line C — The docstring says the function returns the area, but this line calculates the perimeter. Internal documentation must match what the code does. It should be return w * h.
Question 2
A def total(prices):
B """Add up all prices.""
C return sum(prices)
Line B — The docstring is closed with only two quotation marks, so Python sees an unfinished string and gives a syntax error. A docstring must end with three quotation marks.
Question 3
A # Module: grades.py
B # Purpose: average of marks
C // Input: list of marks
D # Output: the mean as a float
Line C — Python comments start with #, not //. This header comment documents the module's inputs and would cause a syntax error. It should be # Input: list of marks.
Question 4
A def show_help():
B """Show user help."""
C print("Enter a mark 0-100")
D print("Type q to quit"
Line D — The closing bracket is missing, so the function that prints the user help text will not run. It should be print("Type q to quit").
Question 5
A def circle_area(r):
B # Inputs: r, the radius
C Output: area as a float
D return 3.14159 * r ** 2
Line C — The # is missing, so Python tries to run the documentation as code and gives a syntax error. Comments that record outputs must start with #.

Student with a class code? Join your class →