Dokumentieren lernen – auch für eigene Projekte

Traditionell wird häufig von der Dokumentation als »das Schreckgespenst« der BwInf-Teilnehmer geredet. Und wie viele auch selbst wissen, kommentieren viele Programmierer auch nicht gern. Dies kann leider dazu führen, dass andere Entwickler sich nicht in ein Projekt einarbeiten können. Tatsächlich passiert es auch, dass man selbst nach einiger Zeit, in der man z. B. an einem anderen Projekt gearbeitet hat, seinen eigenen Code und die Konzepte dahinter nicht mehr versteht.

Eine vernünftige (nicht unbedingt umfangreiche) Dokumentation kann nicht nur dabei helfen, anderen (und später sich selbst) die (Wieder)Einarbeitung zu erleichtern. Denn bei einer Dokumentation geht es im Kern darum, von Grund auf zu erklären, was ein Projekt tut, wie es das tut, was Bestandteile tun und eventuell wozu es gut ist (beim BwInf liegt der Fokus natürlich auf dem zweiten Punkt). Eine Dokumentation kann aber auch helfen, den Entwicklungsprozess erheblich zu beschleunigen und zur Arbeit zu motivieren. (Und nicht um sonst steht im Vorwort der Aufgabenstellung der 2. Runde des BwInf: »Das Erstellen der Dokumentation sollte die Arbeit an Lösungsideen und Umsetzung eng begleiten. Wer zunächst die Lösungsidee verständlich formuliert, dem fällt anschließend eine fehlerlose Implementierung leichter.«)

Eine mögliche Herangehensweise

Die wichtigste Grundüberlegung ist: es gibt keine Gedanken, die komplett irrelevant für das Projekt sind. Selbst wenn ein Lösungsansatz fast offensichtlich falsch/ungeeignet ist, kann es wertvoll sein, darauf hinzuweisen. Jeder, der sich das Projekt anschaut (auch man selbst beim BwInf, wenn man immer und immer wieder Lösungsansätze sucht), wird eventuell auf genau diesen Ansatz (immer wieder) kommen und dann sehen, dass über den Ansatz schon nachgedacht wurde.

Dies ist übrigens der wichtigste Grundsatz dieser Herangehensweise: Oft scheitert das Aufschreiben an Faulheit oder daran, dass vermeintlich falsche Ansätze peinlich sind. Nebenbei sei angemerkt: Versionskontrollsysteme wie git sind auch beim Schreiben von Dokumenten nützlich, aber bei einer Ideenskizze, wie unten beschrieben, nicht immer sinnvoll. Erstens sieht eine Ideenskizze vor, dass ohnehin nie etwas aus dem Dokument gelöscht wird, es gibt also nichts, was im Notfall ernsthaft wiederhergestellt werden könnte. Zweitens kann eine Versionskontrolle hemmen, auch unvollständige Gedanken aufzunehmen. Außerdem werden in der Skizze selbst bereits die Gedanken zusammengefasst, sodass ein einzelner Arbeitsschritt (im Wesentlichen das Hinzufügen eines Gedankens) kaum in einer Commit-Message weiter zusammengefasst werden kann (die letzten beiden Punkte hängen aber von persönlicher Präferenz ab)

Indem man alle Ansätze und Gedanken (skizzenhaft) aufschreibt, kann man sich auch selbst helfen, Gedanken zu organisieren und systematischer neue Gedanken zu entwickeln. Eine Methode könnte sein, in einem Markdown-Dokument pro Ansatz ein Kapitel mit Stichpunkten zu erstellen und in jedem Kapitel Vor- und Nachteile/Stärken und Schwächen des Ansatzes zusammenzufassen. Damit vermeidet man auf der einen Seite, wie schon angesprochen, Wiederholungen derselben Gedanken und merkt auch, wenn sich doch plötzlich ein neues (möglicherweise sehr entscheidendes!) Detail geändert/eingeschlichen hat. Auf der anderen Seite kann man in so einer Übersicht auch schneller sehen, ob sich Ansätze oder Teilideen zu neuen, besseren (vorläufigen) Ideen kombinieren lassen (die natürlich wieder aufgeschrieben werden müssen!). Geht man so vor, so entsteht ganz automatisch eine gute Einführung in die Arbeit; mit allen Gedanken, die man haben kann/muss, um den Entwicklungsprozess der Konzepte hinter dem Projekt zu verstehen.

Ist eine Idee bereits sehr konkret und genau ausformuliert, bietet es sich an, einen Algorithmus in einer etwas formaleren Form anzugeben, z. B. Pseudocode oder sogar schon eine kurze fertig implementierte Funktion in der Zielsprache. Je formaler man eine Idee formuliert, desto mehr ist man auch gezwungen, genau über die Korrektheit nachzudenken.

Geht es bereits in Richtung Umsetzung, kann man dazu übergehen, funktionale Bestandteile eines Ansatzes zu definieren. Also z. B.: Welche Datenstrukturen brauche ich? Welche Operationen müssen darauf angewendet werden? Welche Funktionalitäten könnte ich auch woanders wiederverwenden, müssen also in eigenen Funktionen implementiert werden? Gerade das Aufteilen des Codes auf viele, kleine Funktionen erleichtert sowohl zunächst das Experimentieren, ob einzelne Grundbestandteile oder erarbeitete Formeln funktionieren, als auch später die Implementierung und ermöglicht ausführliches, genaues Testen aller Bestandteile (und erhöht die Lesbarkeit des Codes sowie die Modularisierbarkeit etc.) Das Experimentieren mit bereits implementierten Teilfunktionalitäten kann auch dazu motivieren, verwendete Ideen zu verbessern oder zu verwerfen, wenn sie nicht funktionieren.

Ist schließlich die funktionierende Idee gefunden und eventuell schon implementiert, kann man eine Reinform der Dokumentation schreiben.

Für den BwInf

Beim BwInf sollte (nach Aufgabenstellung, dies muss aber konkret an der Aufgabe und dem Ansatz abgeschätzt werden) kurz und präzise alles Nötige erklärt werden: »eine gute Dokumentation vermittelt kurz und präzise alles Nötige, insbesondere die wesentlichen Ideen beim Lösungsweg.« Die Ideenskizzen können in diesem Schritt wesentlich dabei helfen, zu verstehen, was zur Erklärung gehört: Wenn Ideen aus anderen Ideen motiviert/kombiniert wurden, bilden diese gewissermaßen einen Abhängigkeitsgraphen. Alles, dieser Abhängigkeitsgraph enthält, kann potenziell in die Dokumentation aufgenommen werden. Unveränderte Teilideen sollten dabei natürlich nicht doppelt erklärt werden. Wenn außerdem eine ursprüngliche Idee im Laufe der Entwicklung fast komplett verworfen wurde, so muss (sollte) diese auch nicht unbedingt aufgenommen werden. Am Ende sollte, wie im Vorwort der Aufgabenstellung spezifiziert, so kurz und präzise wie möglich alles erklärt werden, was man braucht, um den Lösungsansatz und die Umsetzungsentscheidungen zu verstehen.

Für eigene Projekte

Bei anderen Projekten kann es je nach Kontext sinnvoll sein, auch mit in die Dokumentation aufzunehmen, warum man sich gegen einen Ansatz und für einen Anderen entschieden hat. So können andere Entwickler (oder man selbst später) andere alternative Lösungsverfahren nachimplementieren. In diesem Sinne kann auch hier die Ideenskizze dabei helfen, zu identifizieren, welche Ideen für die Herleitung des gewählten Ansatzes und für das Verständnis der Entscheidungen sinnvoll sind.

Zur Motivation

Erwähnt sei an dieser Stelle auch noch der Effekt von Motivation beim Programmieren. Lange an einem Projekt zu arbeiten, ohne dass ein Algorithmus funktioniert – ohne Zwischenergebnisse – kann sehr ermüdend sein. Macht man sich dagegen vorher Gedanken, wie die Algorithmen eigentlich funktionieren und welche funktionalen Bestandteile man mit wenig Aufwand implementieren kann, so hat man z. B. mit dem vorgestellten Vorgehen einen Arbeitsablauf, an dem man kontinuierlich weiterarbeiten kann. Diese kontinuierliche Arbeit ist weniger ermüdend. Sie hilft zwar nicht direkt dabei, gute Ideen schneller zu finden – aber sorgt für regelmäßigen sichtbaren Fortschritt. Dokumentieren hilft also nicht nur anderen, ein Projekt zu verstehen, es kann auch den Arbeitsprozess beschleunigen und wesentlich motivieren.