Staying maintainable

A script that works has been running in the cold store for weeks. Now the switch-off limit should move from 2 to 4 °C. You open the chip and find sge c a 275.15. Which register was the temperature again? Is 275.15 the limit or a conversion value? Maintainable code answers these questions before you ask them.

Settings at the top#

Everything a person might ever want to adjust sits as a define at the very top, with unit and meaning in the comment. Limits, times, bands, fault values. The body does not contain a single number anyone might want to change. Whoever changes the limit changes one line and does not need to understand the rest.

Clear names#

alias a r0 saves four characters and costs thinking every single time. alias tStore r0 says what is in it. The same goes for devices: a device is called “Kuehllager”, not “Sensor3”. If everything that belongs to the cold store has that name, you find it in the game and in the code straight away.

Documenting changes#

A short header is enough: what the script does, which version, who. Add a define VERSION that the chip writes onto the housing at start. Then you can see at a glance in the game which revision is running.

# --- Cold store ---
# Version 2, Dominik1199
# v2: off limit 4 C instead of 2 C (vegetables froze)
define VERSION 2 # revision of this script
define EIN 281.15 # 8 C, cool above
define AUS 277.15 # 4 C, stop below

The chip is the wrong place for the list of all changes – every comment line costs characters from the 4096. Only note the latest change and its reason in the script. The old revisions live in your library.