Hallo zusammen,
hab mal eine scheinbar nicht ganz alltägliche Frage zur
Programmierung...
Im Rahmen meines Technikerprojektes ist es notwendig, den Programmcode
meiner Microcontroller Lösung zu dokumentieren. Es soll also eine Art
"Bedienungsanleitung" zu der von mir geschriebenen Software entstehen.
Bisher habe ich die Dokumentation der AVR-Lib als vorbild genommen.
Diese ist z.b. unter AVR-Studio zu bewundern, oder aber online hier...
http://www.nongnu.org/avr-libc/user-manual/index.html
An sich doch eine Recht informative und übersichtliche Sache, oder gäbe
es eurer Seits Verbesserungen, die ich mit übernehmen könnte ?
Mit der Dokumentation steht und fällt meiner Meinung nach die
Verwendbarkeit eines Programmes. Wenn die Dokumentation schlecht ist,
wird das programm wahrscheinlich auch nur sehr ungern weiterverwendet,
wenn überhaupt. Das ganze soll aber zur Schulischen weiterverwendung
geschrieben werden. Die Nachfolgenden Klassen sollen daraus ja auch ihr
neues Wissen ziehen können.
Worauf sollte ich dabei eurer Meinung nach besonders achten, welche
Dinge besser weglassen oder auf jedenfall mit reinnehmen?
Gruss Maggus ;)
Als Vorbild für meine Dokumentaion hab ich speziell diesen Teil der
Website genommen. Somit würe sich das ganze wohl eher "Referenz" als
"Dokumentation" nennen.....
http://www.nongnu.org/avr-libc/user-manual/modules.html
Hallo Markus,
das kannst du mit doxygen machen.
Deine Sourcefiles mußt du entprechend vorbereiten und dann mit doxygen
"compilieren."
Nachfolgend noch einmal ein hilfreicher Link.
[[Beitrag "Automatisches Kommentieren von Code"]]
Gruss Nobbie
Das ist nicht was ich meine ,aber trotzdem Danke ;)
Die Quellcode Kommentare sind alle schon geschrieben.
Ich meine eine Handschriftliche Dokumentation über das ganze Programm.
Z.b. das erst ein Flussdiagramm das die Hauptschleife beschreibt rein
kommt, danach die einzelnen Bibliotheken beschrieben werden und die
Funktionen im einzelnene.
Eine Softwaredokumentation eben, die leicht verständlich und nicht
unnötig überlastet ist .....
Vielleicht ist die Frage auch bisschen blöd fürs Forum. Sollte
eigentlich jedem entwickler seine eigene Sache sein wie er Dokumentiert,
aber evtl. hat ja doch jemand schon erfahrungen damit gesammelt.....
Eben das macht Doxygen doch.
Nur eben das deine Komentare eine etwas andere Form haben.
Der Inhalt ist der gleiche.
Sogar flussdiagramme werden automatisch gezeichnet.
Markus wrote:
> Vielleicht ist die Frage auch bisschen blöd fürs Forum. Sollte> eigentlich jedem entwickler seine eigene Sache sein wie er Dokumentiert,> aber evtl. hat ja doch jemand schon erfahrungen damit gesammelt.....
Nein, du siehst das schon richtig. Wie du an den Antworten siehst,
meinen viele Entwickler, eine Beschreibung der Funktionen und Module
reiche voellig aus. Leider fehlt dann bei dieser Art der Dokumentation
voellig die Beschreibung der Zusammenhaenge, der grosse Ueberblick
sozusagen. Schreibe das ganze wirklich so, als wolltest du Jemandem
Stueck fuer Stueck erklaeren, was du da kreiert hast. Am Besten faengst
du damit an, was das Programm eigentlich tut - sollte man nicht glauben,
aber das wird gerne vergessen.
>Leider fehlt dann bei dieser Art der Dokumentation>voellig die Beschreibung der Zusammenhaenge
das funktioniert, wenn du eine lib geschrieben hast.
aber du willst ja ein programm dokumentieren.
>Im Rahmen meines Technikerprojektes ist es notwendig, den Programmcode>meiner Microcontroller Lösung zu dokumentieren. Es soll also eine Art>"Bedienungsanleitung" zu der von mir geschriebenen Software entstehen.
Das kannst du ja machen. Nur musst du dich entscheiden, ob das eine
Bedienungsanleitung für den Benutzer des Gerätes bzw, der Software wird
(der sich überhaupt nicht für Funktionsaufrufe oder Parameter
interessiert), oder eine Softwaredokumentation bzw.
Schnittstellendokumenation des Quellcodes.
Für ersteres nimmst du das Textprogramm deines Vertrauens, und schreibst
einen schönen Text mit vielen Bildern.
Für lezteres empfiehlt sich das, was hier schon vorgeschlagen wurde:
Doxygen. Die avr-libc hast du ja schon selber als Beipiel genommen.
Schau dir auch mal die Online-Doku zur avrlib an:
http://www.mil.ufl.edu/~chrisarnold/components/microcontrollerBoard/AVR/avrlib/docs/html/index.html
Fast alles, was du da siehst, wurde automatisch aus dem Quellcode
erzeugt. Natürlich muß das da auch alles irgendwo drinstehen.
Oliver
Markus wrote:
> Ich meine eine Handschriftliche Dokumentation über das ganze Programm.> Z.b. das erst ein Flussdiagramm das die Hauptschleife beschreibt rein> kommt, danach die einzelnen Bibliotheken beschrieben werden und die> Funktionen im einzelnene.
Das ist in 99% der Fälle unsinnig. Überleg mal: Du hast einen Quelltext
vor dir liegen. In den schreibst du Kommentare, damit sich der Quelltext
sauber und leicht lesen und verstehen lässt. Dann kritzelst du nochmal
alles in Form von Diagrammen. Und jetzt liest du aufm Monitor den
Quelltext und blätterst gleichzeitig in deiner Diagrammschrift rum...
Spätestens bei der nächsten Änderung des Quelltextes passt nichts davon
mehr zusammen :-D
Also ernsthaft: Guter Programmtext lässt sich auch gut lesen. Als
Daumenregel kann man sagen: Wird die Dokumentation des Quelltextes (also
die 'Diagrammbeschreibung', damit meine ich nicht die Beschreibung
eines API) länger als der Quelltext selbst, dann ist fast immer der
Quelltext verbockt (z.B. unnötig kompliziert formuliert usw.).
Eine eigene Frage?
Dieser Thread ist über 17 Jahre alt.
Stell sie in einem eigenen Thread – dort lesen mehr Leute mit, und sie wird öfter und schneller beantwortet.
