Home A - Z
Page Index

An Otter Wiki

Blame

36b863 lisa 2026-08-12 09:10:36
Add C07 study pages; regenerate C06 via the shared port script sd/C07: home + Naming Conventions, Internal Documentation, Validation Techniques (21 skill codes), linked from the SD hub. sd/C06 pages regenerated by sat/port-reference-godot-to-wiki.py (marker update; C06-home now generated from the repo README like every other page). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 
<!-- 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. -->
2
# Internal Documentation — GDScript
3
4
**Skill codes on this page — all nine are ✍️: written prose required, the label alone earns nothing.**
5
6
| Code | Level | Skill |
7
|---|---|---|
8
| C712 ✍️ | 1–2 | identifies functioning |
9
| C722 ✍️ | 3–4 | outlines functioning |
10
| C732 ✍️ | 5–6 | describes functionality |
11
| C733 ✍️ | 5–6 | describes use of data |
12
| C734 ✍️ | 5–6 | evidence of code maintenance |
13
| C742 ✍️ | 7–8 | explains functionality |
14
| C743 ✍️ | 7–8 | explains use of data |
15
| C744 ✍️ | 7–8 | explains use of code structures |
16
| C752 ✍️ | 9–10 | explains ALL, clear and concise |
17
18
**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).
19
20
**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.
21
22
**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.
23
24
## C712 — Identify the functioning
25
26
One written line naming what the program (or feature) does:
27
28
```gdscript
29
## C712 — Myki fare app: calculates fares by zone and tracks the card balance.
30
```
31
32
**Earns the tick:** a true sentence about *your* program's purpose. **Doesn't:** a label with no sentence.
33
34
## C722 — Outline the functioning (header comment)
35
36
**Definition.** *Header comment:* meaningful comments at the top of a source code file — the file's name, purpose, author and date.
37
38
```gdscript
39
## fare_calculator.gd — Myki fare app # C722 — header comment
40
## Purpose: reads the zone, works out the fare (with the
41
## concession discount), charges the card and updates the display.
42
## Author: <you> Created: 2026-07-28
43
```
44
45
**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`).
46
47
## C732 — Describe the functionality
48
49
Level 5–6: each function documented with **what it does**:
50
51
```gdscript
52
# club-ladder — ladder.gd
53
## Throw away the old rows and build one row per team, in ladder order. # C732
54
func build(teams: Array[Team], win_value: int, draw_value: int) -> void:
55
```
56
57
**Earns the tick:** every function in the picked feature has a doc line that describes its job accurately.
58
59
## C733 — Describe the use of data
60
61
What each variable or structure **stores, and what it is used for**:
62
63
```gdscript
64
# tile-matching-game — card.gd
65
## Cards with the same pair_id match each other. Two cards in a pair can show
66
## completely different things — matching compares this id, not what is on screen.
67
var pair_id := "" # C733 — describes what the data means, not just its type
68
```
69
70
```gdscript
71
var balance: float = 20.00 # C733 — money left on the card, in dollars
72
```
73
74
**Synergy:** the *why-this-type* comments C6 asked for (C629/C638) are C733 evidence too — one comment, marks on both criteria.
75
76
## C734 — Evidence of code maintenance
77
78
Comments that record a **fix, change or lesson learned** — proof the code has been maintained, not written once:
79
80
```gdscript
81
# tile-matching-game — game.gd
82
# The board may have been rebuilt while we were waiting. # C734 — records the bug this guards against
83
if is_instance_valid(first_card):
84
first_card.flip_down()
85
```
86
87
```gdscript
88
# board.gd
89
# add_child() first so the card's @onready variables exist, # C734 — lesson learned, kept for the next reader
90
# then fill in what it should show.
91
```
92
93
A dated changelog line also works: `# C734 — 2026-08-01 fixed: fare charged twice when touching on within 2s`.
94
95
**Earns the tick:** a comment that could only exist because the code *changed* — a fixed bug, a guarded edge case, a recorded decision.
96
97
## C742 / C743 / C744 — Explain (the why)
98
99
Level 7–8 upgrades the verb: not *what*, but **why it works this way**.
100
101
**C742 — explains functionality:**
102
103
```gdscript
104
# club-ladder — app.gd
105
## Every change goes through here, so there is exactly one place that could # C742
106
## forget to save — rather than one place per button.
107
func refresh() -> void:
108
```
109
110
**C743 — explains use of data:**
111
112
```gdscript
113
# club-ladder — team.gd
114
## Games played is worked out, not stored. If we stored it as well we would # C743
115
## have two places to keep in step, and one day they would disagree.
116
func played() -> int:
117
return wins + draws + losses
118
```
119
120
**C744 — explains use of code structures:**
121
122
```gdscript
123
# club-ladder — team.gd
124
## Points are worked out too, but a Team cannot do it alone: what a win is # C744
125
## worth is the competition's rule, not the team's. So the caller hands the rule in.
126
func points(win_value: int, draw_value: int) -> int:
127
```
128
129
**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.
130
131
## C752 — Explain everything, clear and concise
132
133
Level 9–10: the whole picked feature documented at explain level — **all** data, **all** code structures — with no noise:
134
135
```gdscript
136
age += 1 # add 1 to age ← noise: repeats the code
137
age += 1 # C752 — birthday passed; drives the concession re-check below
138
```
139
140
**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.
141
142
## Check Your Understanding
143
144
1. What does ✍️ mean on a C7-2 code, and what happens if you label but write nothing?
145
146
>| ### Answer
147
>| Written evidence required — real prose in the comments. A label with no writing earns nothing on all nine C7-2 codes.
148
149
2. Describe vs explain — what is the upgrade?
150
151
>| ### Answer
152
>| Describing says *what* it does or stores; explaining says *why* it works that way — often by naming the rejected alternative.
153
154
3. Give one thing that counts as evidence of code maintenance (C734).
155
156
>| ### Answer
157
>| 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.