Documentation-Driven Development

Es ist etwa 6 Monate her, seit ich das letzte Mal etwas Zeit gefunden habe, um an DiaVN zu arbeiten, und ich habe es endlich geschafft, wieder damit anzufangen. Die erste brauchbare Version, wenn auch begrenzt (Fähigkeit, ein Dia-Diagramm zu nehmen und RenPY-Code zu erzeugen), wird bald verfügbar sein.

Das Schwierigste, wenn man mit wenig Zeit an großen Projekten arbeitet, ist, sich wieder in die Arbeit einzufinden. Nach sechs Monaten hatte ich große Schwierigkeiten zu verstehen, was ich gemacht habe, wie ich es gemacht habe und warum ich es gemacht habe, und an diesem Punkt wurde mir klar, dass meine Dokumentation unzureichend war - nicht, dass sie nicht vorhanden gewesen wäre, aber sie war nicht aus der Perspektive geschrieben, dass ich das Projekt nur zweimal im Jahr angefasst habe.

Was genau fehlte ?

• Zuallererst eine nicht-technische Dokumentation, die die Architektur des Projekts sowie die Besonderheiten der für die Diagramme verwendeten „Syntax“ beschreibt.
• Aber auch eine genaue Auflistung der zu lösenden Fragen, der noch zu erledigenden Aufgaben und des Stands der Entwicklung des Projekts

Da mein Projekt noch nicht auf github ist (es wird erst dort sein, wenn es die erste öffentliche Version sein wird), hatte ich nicht die Möglichkeit, die Issues als Todolisten zu verwenden, und meine einzige Möglichkeit war, Kommentare im Code zu hinterlassen, in der Hoffnung, dass ich nach all dieser Zeit wieder etwas daraus machen würde.

Also beschloss ich, die Projektdokumentation als „Willkommen zurück“-Aufgabe neu zu schreiben und zu vervollständigen, und ich nutzte das erstaunliche Sphinx Tool für diese Aufgabe.

Ich begann damit, den nicht-technischen Teil der Dokumentation zu schreiben, dann tauchte ich in meinen Code ein und schrieb die technische Dokumentation neu. Ich benutzte das „sphinx.ext.todo“-Plugin, um mir eine sich entwickelnde TODO-Liste zu erstellen, die alle im Code verstreuten TODOs aufnimmt.

Als ich so weitermachte, wurde mir klar, dass testgetriebene Entwicklung eine großartige Sache ist, sicher, aber der erste Schritt ist vorher, nämlich in natürlicher Sprache zu beschreiben, was wir tun wollen, und das ist eigentlich das Schreiben von Dokumentation. So kam mir der Gedanke, dass eine bessere Methode eine Art „dokumentationsgesteuerte Entwicklung“ wäre, bei der ich zuerst schreibe, was ich tun möchte (mit normalen Worten), dann die Tests zur Überprüfung der beschriebenen Szenarien programmiere und schließlich den Code zur Umsetzung der Idee schreibe.

Zufälligerweise ist die dokumentationsgestützte Entwicklung eine echte Sache, auch wenn sie noch nicht sehr bekannt ist, und es gibt einige Ressourcen im Internet (z.B. dieser Beitrag hier). Als ich mich mit dem Thema beschäftigte, stieß ich auf jemanden, der sagte, das Konzept erinnere ihn an etwas, das Donald Knuth (der Stanford-Professor, der „The Art of Computer Programming“ veröffentlicht) erfunden hat, und das „literate programming“ genannt wird. Bei dieser Methode werden Code und Dokumentation zusammen als ein Dokument geschrieben, in dem sich Beschreibungen und Gedanken zu einem Projekt mit Schnipseln abwechseln, die zeigen, wie es funktioniert. Zur Kompilierungszeit extrahiert ein spezielles Tool den Code aus dem Programm und kompiliert ihn, während ein anderes Tool die Dokumentation formatiert.

Mit diesem Mashup ist es ganz natürlich, die Dokumentation zu bearbeiten, wenn man den Code bearbeiten muss - normalerweise ändern wir den Code, um Fehler zu korrigieren oder neue Ideen zu implementieren, und das wird natürlich zuerst in natürlicher Sprache geschrieben.

Ich habe die Literate Programmierung nicht in DiaVN implementiert, aber ich werde es auf jeden Fall ausprobieren und bei meinem nächsten Aufenthalt ein Literate Programmierer werden !