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.).
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.