CDP – Code Documentation Practice

Letzte Änderung am 17. Dezember 2019 by Christoph Jüngling

Notebook, Block, BleistiftDieser Artikel ist der Start einer kurzen Reihe von Empfehlungen für die Dokumentation von VBA-Code und den Applikationen. Prinzipiell sind das alles keine völlig neuen Ideen. Ich habe das, was andere auch tun, nur etwas an die VBA-Welt angepasst.

Vor längerem habe ich mal ein Whitepaper für den Access-Profi-Pool geschrieben, das dort leider nicht mehr verfügbar ist. Das hier nun beschriebene Prinzip stellt eine etwas andere und vor allem erweiterte Umsetzung dar als damals beschrieben, aber im Grunde verfolgen beide Formate den selben Zweck.

Begriffsdefinition

Der Begriff Code Documentation Practice kam mir in den Sinn, als ich über Good Documentation Practice (siehe Wikipedia deutsch / englisch) im Zusammenhang mit Quellcode nachgedacht habe. Analog dazu verwende ich in diesem Blog das Schlagwort CDP statt “GDP”. Die Ähnlichkeit ist natürlich beabsichtigt, denn in beiden Fällen wird das Ziel verfolgt, eine “gute” Dokumentation vorzulegen, die noch dazu immer nach dem gleichen Schema erstellt wird.

Heute ist ein ausgedrucktes Listing in Projekten kaum noch gebräuchlich. Auch sieht man es wohl nicht mehr als angemessene Programmdokumentation an, denn es enthält nicht mehr, als man am Bildschirm auch sehen könnte. Dennoch wurde vor einigen Jahrzehnten genau diese Bedeutung darunter verstanden. Dokumentation, wie ich den Begriff verstehe, beinhaltet also nicht einfach nur “irgendwas mit Papier”, sondern geht weit darüber hinaus.

Ein Qualitätsmanagementsystem soll laut Wikipedia, “(…) detaillierte und ausreichende Aufzeichnungen zur Erleichterung eines allgemeinen Verständnisses (…) beinhalten”. Dieses durch Weglassung leicht veränderte Zitat lässt sich in dieser allgemeinen Form sicher auch auf den Vorgang der Quellcodeverwaltung (Versionsverwaltung) anwenden. Auch hier geht es darum, den Entwicklerkollegen (oder auch mir selbst nach einer gewissen Zeit) das Verständnis für das, was das Programm macht bzw. was daran verändert wurde, zu erleichtern. Denn gerade bei länger laufenden Programmen (Stichwort ALM) kann zwischen der Programmierung einer Klasse und deren Bugfixing eine lange Zeit vergehen. Erinnerst du dich noch an jede Zeile, die du je programmiert hast?

Doch Quellcodeverwaltung ist nicht alles. Denken wir an sinnvolle Bugreports, bei denen wir als Entwickler ein Mindestmaß an wünschenswerten Informationen definieren. Wo sollen die her kommen? Klar, aus der Software selbst. Wir brauchen also eine Art “About”-Dialog, wo alles wissenswerte zusammengefasst ist.

Und letztlich spielt auch der Anwender eine gewisse Rolle. Diesem wollen wir ein Handbuch oder wenigstens eine Online-Hilfe zur Verfügung stellen, damit die bereits seit langem bekannte “F1”-Taste vielleicht wieder zu neuen Ehren kommt.

Mal sehen, was mir noch so alles einfällt. Stay tuned, in ein paar Tagen geht es hier weiter.

Ähnliche Artikel:

Schreibe einen Kommentar

Deine Email-Adresse wird nicht veröffentlicht.

sieben − 1 =