Internal Documentation — GDScript

Skill codes on this page — all nine are ✍️: written prose required, the label alone earns nothing.

Definition. Internal documentation: notes and code comments contained within source code that describe the code. This is the heaviest indicator — nine of C7's 21 codes, worth 40% of the criterion — and the whole ladder is a verb climb: identifies → outlines → describes → explains, with clarity qualifiers deciding the top bands (some issues 5–6 → minor issues 7–8 → clear and concise 9–10).

Godot mechanics: # starts a comment; ## starts a doc comment that Godot renders in the editor's help and hover tips — your documentation becomes real, browsable docs (GDScript's equivalent of Python's pydoc). Use ## for file headers and function docs, # for inline notes.

In the validation Part B you write the internal documentation for the picked feature from scratch on the comment-stripped copy — these patterns are what you'll be reproducing from memory.

C712 — Identify the functioning

One written line naming what the program (or feature) does:

## C712 — Myki fare app: calculates fares by zone and tracks the card balance.

Earns the tick: a true sentence about your program's purpose. Doesn't: a label with no sentence.

C722 — Outline the functioning (header comment)

Definition. Header comment: meaningful comments at the top of a source code file — the file's name, purpose, author and date.

## fare_calculator.gd — Myki fare app                    # C722 — header comment
## Purpose: reads the zone, works out the fare (with the
## concession discount), charges the card and updates the display.
## Author: <you>   Created: 2026-07-28

Earns the tick: a header that outlines the flow — a reader knows what happens in this file without scrolling. In club-ladder every script opens this way: ## The rules. Loads the season, records results, adds and removes teams, and saves after every change. (app.gd).

C732 — Describe the functionality

Level 5–6: each function documented with what it does:

# club-ladder — ladder.gd
## Throw away the old rows and build one row per team, in ladder order.   # C732
func build(teams: Array[Team], win_value: int, draw_value: int) -> void:

Earns the tick: every function in the picked feature has a doc line that describes its job accurately.

C733 — Describe the use of data

What each variable or structure stores, and what it is used for:

# tile-matching-game — card.gd
## Cards with the same pair_id match each other. Two cards in a pair can show
## completely different things — matching compares this id, not what is on screen.
var pair_id := ""   # C733 — describes what the data means, not just its type

var balance: float = 20.00   # C733 — money left on the card, in dollars

Synergy: the why-this-type comments C6 asked for (C629/C638) are C733 evidence too — one comment, marks on both criteria.

C734 — Evidence of code maintenance

Comments that record a fix, change or lesson learned — proof the code has been maintained, not written once:

# tile-matching-game — game.gd
# The board may have been rebuilt while we were waiting.   # C734 — records the bug this guards against
if is_instance_valid(first_card):
    first_card.flip_down()

# board.gd
# add_child() first so the card's @onready variables exist,   # C734 — lesson learned, kept for the next reader
# then fill in what it should show.

A dated changelog line also works: # C734 — 2026-08-01 fixed: fare charged twice when touching on within 2s.

Earns the tick: a comment that could only exist because the code changed — a fixed bug, a guarded edge case, a recorded decision.

C742 / C743 / C744 — Explain (the why)

Level 7–8 upgrades the verb: not what, but why it works this way.

C742 — explains functionality:

# club-ladder — app.gd
## Every change goes through here, so there is exactly one place that could   # C742
## forget to save — rather than one place per button.
func refresh() -> void:

C743 — explains use of data:

# club-ladder — team.gd
## Games played is worked out, not stored. If we stored it as well we would   # C743
## have two places to keep in step, and one day they would disagree.
func played() -> int:
    return wins + draws + losses

C744 — explains use of code structures:

# club-ladder — team.gd
## Points are worked out too, but a Team cannot do it alone: what a win is    # C744
## worth is the competition's rule, not the team's. So the caller hands the rule in.
func points(win_value: int, draw_value: int) -> int:

Earns the tick: the comment answers why — often by naming the alternative you rejected ("if we stored it as well…"). That move is exactly what separates 7–8 from 5–6.

C752 — Explain everything, clear and concise

Level 9–10: the whole picked feature documented at explain level — all data, all code structures — with no noise:

age += 1   # add 1 to age          ← noise: repeats the code
age += 1   # C752 — birthday passed; drives the concession re-check below

Earns the tick: a stranger could maintain the feature from the comments alone, and nothing is written twice or said emptily. Clear and concise is the descriptor's own wording — cutting waffle is part of the standard.

Check Your Understanding

1. What does ✍️ mean on a C7-2 code, and what happens if you label but write nothing?

2. Describe vs explain — what is the upgrade?

3. Give one thing that counts as evidence of code maintenance (C734).