Variablen als Mittel der Code Dokumentation - wie macht Ihr das?

[Bacardi]

Hi

Es ist ein Klassiker unter Entwicklern: Wieviel Code Doku ist wirklich nötig? Die Diskussion geht von “Unnötig, steht doch alles im Code” (Experten) bis “Jede Zeile dokumentieren” (Anfänger). Wie Ihr das für Euch seht, müßt Ihr Euch selbst beantworten. Ist zu wenig dokumentiert, werden nachträgliche Änderungen/Erweiterungen zeitaufwendig und Abhängigkeiten werden manchmal übersehen. Am Anfang meiner HA Reise habe ich zu viel dokumentiert … aus heutiger Sicht 1,5 Jahre später

Wie auch immer, an kniffligen Stellen einer Automatisation oder Scriptes füge ich mittlerweile gerne Variablen ein, nach dem Muster

variables:
  comment: Denk dran diese Aktion hängt mit xyz zusammen
  comment1: Du machst diesen Schritt weil dies und das nötig ist

Vorteil dieser Methode: Man kann genau da platzierten wo man es braucht.
Nachteil: Man sieht nicht alle Notizen zentral

Ein Beispiel
was auch gleich eine Stärke von ChatGPT zeigt.

Ich teste gerade meine neue Heizungslösung durch und stellte fest, daß ich nicht alle Fälle konsequent erdacht und abgearbeitet habe. Ich bat ChatGPT

• mir eine Matrix aller Möglichkeiten aufzustellen/zu vervollständigen
• und die lesbar als Tabelle im Variablen Format zu anzugeben

variables:
  topic: Nacht AN (Wohnzimmer)
  nacht: immer AN
  if0:   "  Fenster  | ZuWarm  | Lüfter  | SusiAbw  "
  ifu:   "  -------------------------------------- "
  if1:   "  AUS      | AUS     | AUS     | AUS     "
  if2:   "  AUS      | AUS     | AUS     | AN      "
  if3:   "  AUS      | AUS     | AN      | AUS     "
  if4:   "  AUS      | AUS     | AN      | AN      "
  if5:   "  AUS      | AN      | AUS     | AUS     "
  if6:   "  AUS      | AN      | AUS     | AN      "
  if7:   "  AUS      | AN      | AN      | AUS     "
  if8:   "  AUS      | AN      | AN      | AN      "
  if9:   "  AN       | AUS     | AUS     | AUS     "
  if10:  "  AN       | AUS     | AUS     | AN      "
  if11:  "  AN       | AUS     | AN      | AUS     "
  if12:  "  AN       | AUS     | AN      | AN      "
  if13:  "  AN       | AN      | AUS     | AUS     "
  if14:  "  AN       | AN      | AUS     | AN      "
  if15:  "  AN       | AN      | AN      | AUS     "
  if16:  "  AN       | AN      | AN      | AN      "

So was kam nach wirklich nur 3-4 Anläufen dann raus und in meinem Code sieht es so aus

Wenn Ihr gute Einfälle zur Doku habt, nur zu.

[simon42]

Hey Bacardi, danke für den spannenden Beitrag!

Finde den Ansatz mit den Variablen als Inline-Doku kreativ – besonders die Idee, sich von ChatGPT eine Matrix aller Fälle als „Variablen-Tabelle" generieren zu lassen. Das ist ein cleverer Workaround für das Fehlen von echten Kommentaren in der HA-Automatisierungs-UI.

Ein Tipp, den ich ergänzen würde: In YAML selbst kann man natürlich auch klassische Kommentare mit # nutzen – die werden in der YAML-Ansicht angezeigt, gehen allerdings verloren, wenn man über die UI editiert. Wer also primär über die UI arbeitet, für den ist dein Variablen-Ansatz eine gute Alternative.

[Bacardi]

Oha, Simon. Du wertest einen Beitrag auf, den ich bei mir schon als Looser von den Zugriffszahlen abgetan hatte. Aber danke natürlich. Die Nutzung von Variablen im Code zur Dokumentation ist bei mir zu einem festen Bestandteil geworden.

Mit # in Yaml ist für mich ein Nogo wenn man abwechselnd im Yaml und grafischen Modus arbeitet. Ich muß mich darauf verlassen können, daß die nicht weggelöscht werden.

[Bacardi]

A friendlier way to add cards to your dashboard - 2026.6: Pick a card, any card

Ich sehe gerade, Notizen kommen, oha

Every trigger, condition, action, option, and script field now has a dedicated **Notes** field, separate from its name.

Das finde ich absolut sinnvoll.

[Jim_OS]

Weil ich mir zufällig genau diesen Punkt gerade mal angeschaut habe.

VG Jim