Sie ist immer dann wichtig, wenn eine Konstruktion, sei es Hard- oder Software, nicht nur dem Ersteller, sondern auch anderen verständlich gemacht werden soll.
Wobei - auch der Ersteller wird sich freuen, wenn er, nach Monaten anderer Tätigkeiten, Änderungen an seinem eigenen Erzeugnis machen soll und natürlich nicht mehr genau weiß, was er damals gemacht und gedacht hat, und warum er dies und jenes so ausgeknobelt hatte und nicht anders.
Auch, wenn mehrere Leute an einem Projekt arbeiten, ist Dokumentation extrem wichtig.
Beispiel:
Ein Stellpult soll gefertigt werden. Einer macht den Plan, der zweite bohrt die Schalttafel und bestückt die Bauteile, und der dritte macht die Verkabelung. Diese Zusammenarbeit funktioniert nur, wenn die der Planung nachfolgenden Arbeiten 'blindlings' gemacht werden können; es darf hier kein 'Wenn und Aber' geben. Eine Fehlersuche gelingt nur dann effektiv, wenn wirklich alles 'nach Plan' gelaufen ist, und wenn niemand 'auf Gutdünken' gearbeitet hat und sich nicht an den Plan gehalten hat.
Wenn man sich dies alles einmal zu Gemüte geführt hat, wird es schnell klar, daß eine Dokumentation vor der Fertigung zu erfolgen hat, nicht 'während' und schon gar nicht nachher!
Das 'Nachher' ist nämlich von ganz besonderem Übel. Hier schleichen sich Fehler ein, die nicht bemerkt werden, und die erst nach Jahren Probleme aufwerfen werden.
Das Erstellen einer Dokumentation als erstem Schritt hat auch den wesentlichen Vorteil, daß die anschließende Fertigung die Kontrolle darüber ist, ob jene richtig und korrekt war.
Warum dieses hier als Teil der PIC-Tips steht?
Weil eine Programmierung eines PICs eine extrem unübersichtliche Sache ist, und weil hier die Fehlersuche oder die evtl. spätere Änderung einer Funktion nur dann gelingt, wenn alles, aber auch wirklich alles dokumentiert worden ist. Die Dokumentation muß hier vom Umfang her viel größer sein als das eigentliche Programm. In die "Überschrift" eines Programms gehört zumindest die Beschreibung der Funktion (was macht das Programm?), dazu die Eingangs- und Ausgangsdaten (welche Daten braucht das Programm und was liefert es wieder ab?) sowie eine Beschreibung der Fehlermeldungen (was ist passiert, wenn eine bestimmte Meldung auftritt, und wie kann man dies vermeiden?).
Wir haben den Umfang einmal ausgezählt an unserem Programm für die Lichtsignalsteuerung:
- 206 Zeilen nur für Dokumentation,
- 195 Befehlszeilen insgesamt,
- nur 85 davon ohne Kommentar.
Mit anderen Worten: Das Programm ist 401 Zeilen lang. In 85 Zeilen steht kein Kommentar. Sehr viele dieser Zeilen enthalten Sprungadressen oder so einfache Befehle wie 'return'. Da hätte man beim Auswerten herumtricksen und diese Zeilen woanders verstecken können. Das wollten wir aber nicht. Das Verhältnis der Zahlen ist anschaulich genug. Diese Auszählung haben wir ganz spontan Monate nach der Fertigstellung vorgenommen; wir binden Ihnen hier also keinen Bären auf.
Somit kann jemand, der das Programm ändern will, sich erst einmal einlesen, was wo und wie und warum gemacht worden ist.
Fazit:
Nehmen Sie sich sehr viel Zeit für Dokumentationen. Sie werden es später viel leichter haben.
----------
... und jetzt sind wir endlich direkt am PIC:Zu einer guten Dokumentation gehört aber auch die Aussage, was für ein Programm in einem PIC steckt. Von außen ist es nicht zu erkennen. Wir haben uns dazu entschlossen, auf Papier kleine Schildchen zu drucken und diese dann auf die PICs zu kleben. Weiterhin gehört natürlich die Bezeichnung auf dem Schild in die entsprechende Programm-Dokumentation. Aber das versteht sich eigentlich von selbst. Bei der Fertigung des Schildchens muß darauf geachtet werden, daß die Markierung für den Pin 1 nicht zugedeckt wird oder deutlich auf dem Schild steht, wie wir es vorziehen: gerade bei kleinen PICs hat man so mehr Platz für den Text auf dem Schild.
Die Schildchen werden mit einem Grafik-Programm erstellt und dann maßstäblich mit einem Laserdrucker zu Papier gebracht.
Ein kleiner Tip nebenbei:
Wenn man nach dem Drucken auf das Schildchen einen "Tesafilm" klebt und es erst dann (z.B. mit einem Skalpell und einem Stahllineal) ausschneidet, dann hat man einen wunderbaren Oberflächenschutz. Wir haben nämlich festgestellt, daß die Druckqualität nur durch den Vorgang des Aufklebens erheblich leidet. Dies ist besonders schlimm bei Sub-Miniatur-Schildchen, wie wir sie z.B. auf den SMD-PICs bei den Servo-Antrieben verwenden.
Links sehen Sie ein Schildchen auf einem PIC der Baugröße SO-8, das nur durch den Vorgang des Aufklebens
so gut wie unleserlich wurde; rechts ein Schild aus demselben Drucker, nur vor dem Aufkleben durch eine Klebefolie
geschützt.
'Murphy' hätte all dies auf einen kurzen Satz gebracht:
"Eine Dokumentation ist immer zu dürftig."
Für weitere Fragen stehen gern zur Verfügung:
- der MEC; Besichtigung und Fachsimpelei z.B. an unseren "Club-Abenden"
- der Autor: Hans Peter Kastner