<!-- Generated from applied-computing-au vic/unit3-4/sat/C07-2026/C07-Reference-Godot by port-reference-godot-to-wiki.py — do not hand-edit; re-run the port. --> # Internal Documentation — GDScript **Skill codes on this page — all nine are ✍️: written prose required, the label alone earns nothing.** | Code | Level | Skill | |---|---|---| | C712 ✍️ | 1–2 | identifies functioning | | C722 ✍️ | 3–4 | outlines functioning | | C732 ✍️ | 5–6 | describes functionality | | C733 ✍️ | 5–6 | describes use of data | | C734 ✍️ | 5–6 | evidence of code maintenance | | C742 ✍️ | 7–8 | explains functionality | | C743 ✍️ | 7–8 | explains use of data | | C744 ✍️ | 7–8 | explains use of code structures | | C752 ✍️ | 9–10 | explains ALL, clear and concise | **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: ```gdscript ## 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. ```gdscript ## 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**: ```gdscript # 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**: ```gdscript # 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 ``` ```gdscript 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: ```gdscript # 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() ``` ```gdscript # 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:** ```gdscript # 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:** ```gdscript # 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:** ```gdscript # 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: ```gdscript 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? >| ### Answer >| Written evidence required — real prose in the comments. A label with no writing earns nothing on all nine C7-2 codes. 2. Describe vs explain — what is the upgrade? >| ### Answer >| Describing says *what* it does or stores; explaining says *why* it works that way — often by naming the rejected alternative. 3. Give one thing that counts as evidence of code maintenance (C734). >| ### Answer >| A comment recording a fix, a guarded edge case, or a lesson learned — e.g. "The board may have been rebuilt while we were waiting", or a dated fixed-bug line.