Scripts dokumentieren

Ein Mitspieler baut dein Lagerlicht nach und meldet: „Geht nicht.“ Nach zehn Minuten stellt sich heraus, dass sein Bewegungsmelder „Lagerraum“ heißt. Mit einer Zeile Dokumentation wäre das nicht passiert. Dokumentation ist nicht für dich heute, sondern für dich in einem halben Jahr und für jeden, der dein Script übernimmt.

Der Kopfkommentar#

Ganz oben steht, was man wissen muss, bevor man irgendetwas baut:

# === Lagerlicht ===
# Zweck: Licht im Lager nach Bewegung, mit Nachlauf
# Version 3, Dominik1199
# Geraete (Name / Prefab / Aufgabe):
#   Lager / StructureMotionSensor / Bewegung
#   Lager / StructureWallLight / Licht
#   Version / StructureConsoleLED5 / zeigt VERSION

Zweck, Version und Autor in je einer Zeile. Darunter die Geräteliste: jeder Name, den das Script per HASH("…") sucht, mit Prefab und Aufgabe. Wer die Liste abarbeitet, hat die Anlage richtig benannt – auch der Mitspieler mit dem „Lagerraum“.

Einstellwerte erklären#

Ein define-Kommentar beantwortet drei Fragen: Einheit, sinnvoller Bereich, Wirkung.

define NACHLAUF 10 # Durchlaeufe Licht nach Bewegung, 10 = 5 s

„10“ allein sagt nichts. „Durchläufe“ sagt die Einheit, „10 = 5 s“ übersetzt sie in etwas, das man sich vorstellen kann. Bei Temperaturen steht Celsius neben dem Kelvin-Wert, bei Anteilen der Prozentwert.

Wenn die Zeichen knapp werden#

Ein guter Kopf kostet schnell 300 bis 400 der 4096 Zeichen. Wird es eng, gibt es zwei Fassungen: Die Langfassung mit allen Kommentaren liegt in deiner Bibliothek, die Spielfassung des IC10-Coders entfernt Kommentare und Leerzeilen und läuft im Chip. Die Langfassung ist das Original – geändert wird immer dort, die Spielfassung wird danach neu erzeugt.