www.mikrocontroller.net

Forum: Mikrocontroller und Digitale Elektronik Programmcode Dokumentieren


Autor: Markus (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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 ;)

Autor: Markus (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Nobbie (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Markus (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.....

Autor: Tobias K (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: P. S. (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Bill (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
>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.

Autor: Bill (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
auch wenn das nicht so klar wird, ich wollte peter zustimmen :)

Autor: Oliver (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
>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/mic...

Fast alles, was du da siehst, wurde automatisch aus dem Quellcode 
erzeugt. Natürlich muß das da auch alles irgendwo drinstehen.

Oliver

Autor: Sven P. (haku) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.).

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.
Hinweis: der ursprüngliche Beitrag ist mehr als 6 Monate alt.
Bitte hier nur auf die ursprüngliche Frage antworten,
für neue Fragen einen neuen Beitrag erstellen.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.