Documenting scripts

A fellow player rebuilds your store light and reports: “Does not work.” After ten minutes it turns out that his motion sensor is called “Lagerraum”. One line of documentation would have prevented that. Documentation is not for you today, but for you in half a year and for everyone who takes over your script.

The header comment#

At the very top stands what you need to know before building anything:

# === Store light ===
# Purpose: light in the store on motion, with run-on
# Version 3, Dominik1199
# Devices (name / prefab / job):
#   Lager / StructureMotionSensor / motion
#   Lager / StructureWallLight / light
#   Version / StructureConsoleLED5 / shows VERSION

Purpose, version and author in one line each. Below it the device list: every name the script looks for via HASH("…"), with prefab and job. Whoever works through the list has named the setup correctly – including the fellow player with the “Lagerraum”.

Explaining settings#

A define comment answers three questions: unit, sensible range, effect.

define NACHLAUF 10 # passes of light after motion, 10 = 5 s

“10” on its own says nothing. “Passes” gives the unit, “10 = 5 s” translates it into something you can imagine. For temperatures Celsius stands next to the Kelvin value, for ratios the percentage.

When characters get tight#

A good header quickly costs 300 to 400 of the 4096 characters. If it gets tight, there are two versions: the long version with all comments lives in your library, the IC10 coder's game version strips comments and blank lines and runs in the chip. The long version is the original – changes are always made there, and the game version is generated again afterwards.