# Wie dokumentiert ihr?



## jccTeq (7. Oktober 2004)

Hallo Leute,

Konzeptfrage: in welcher Form dokumentiert ihr euren Code? 

Ich hab die leidige Aufgabe, den Code eines meiner Programme nachträglich  zu dokumentieren. Kein Programmiererhandbuch, da das Programm absolut proprietär ist, aber immerhin Klassen-, Variablen- und Funktionsbeschreibungen innerhalb des Codes und so. Wie sieht das bei euch aus? Ich suche ein schickes und übersichtliches Konzept/Vorgehen dafür oder ein passendes Tutorial, einen Guide oder ähnliches. Ich suche das ultimative Dokumentations-Konzept. 

Ich weiß, nachträglich ist Pup. Hätte ich vorher dran denken müssen. Mit Antworten a'la "Tja, hättst vorher mal dran denken sollen" oder "Hättest gleich beim Coden dokumentieren sollen" kann ich also nix werden. 

Danke euch!

Gruß, 
Hendrik


----------



## michaelwengert (7. Oktober 2004)

meistens so:

```
Variablen normal mit            
         CString   strXyz                         // für irgendwas
Funktionen in der cpp:
          /* Funktion macht dieses und jenes.....*/
         void CUserVerwalten::OnBnClickedExtranew()
          {
          }
```
ich machs meistens auch erst am Schluß.
Dumme Angewohnheit aber was will mann machen.


----------



## darkarchon (7. Oktober 2004)

kurz zu jeder methode schreiben wozu sie da ist, und bie größeren komplexen schleifen oder mathematischen funktionen deine tricks hinschreiben, sonst weisst du die später selbst nicht mehr 

und alles natürlich in englisch !


----------



## RedWing (7. Oktober 2004)

> Ich suche das ultimative Dokumentations-Konzept.



doxygen 

Gruß

RedWing


----------



## jccTeq (7. Oktober 2004)

haha, doxygen hab ich in der Zwischenzeit auch gefunden. Ist 'ne tolle Sache. So schön einfach und doch sehr schick. Auch wenn jetzt ein MEGA HAUFEN Arbeit über mich hinweg rollt. Aber das hab ich mir ja selbst zuzuschreiben.  

Also für alle, die bisher nur im Code dokumentiert haben, schaut euch mal doxygen an. Das Ding ist wirklich genial. Damit macht sogar das Dokumentieren Spaß.  

EDIT: Aaaah noch eins... wie baut man mit Doxygen wohl am besten einen Glossar, bzw. ein Stichwort-Verzeichnis? Geht das überhaupt?

Danke!


----------



## cHillberT (7. Oktober 2004)

Kleine Zeilen Programmcode dokumentiere ich ganz kurz in der selben Zeile und wenn ich größere Konstrukte habe, dann schreib ich über dem gesamten Schleifenkonstrukt zum Beispiel einen größen "Blockkommentar", mit dem ich die wichtigsten Abläufe erkläre !


----------



## canuzzi (7. Oktober 2004)

*Man Pages*

Ich hatte mir schon immer ueberlegt, eigentlich sollte man ja seine Docu als Man Page anlegen. Ich habe dazu schon gegoogelt und natuerlich man man ausprobiert, aber nichts wirklich informatives gefunden. Haette irgendjemand links oder tipps?


----------



## cHillberT (7. Oktober 2004)

Ist es nicht wichtig, dass man am Anfang eine Kommentierweise findet, mit der man am besten selbst klar kommt.
Mit der Zeit übernimmt man, dann eine allgemeingültige Schreibweise davon !


----------



## jccTeq (7. Oktober 2004)

doxygen...


kann auch Manpages anlegen.

Aber nochmal 'ne Frage: seh ich das richtig, daß man C++ Programme nur in den Header-Dateien, also den Klassen-Deklarationen zu dokumentieren braucht? Mal abgesehen von Makros, globalen Funktionen und Variablen (die man ja eigentlich sowieso vermeiden sollte) und der main-Funktion? Das erspart 'ne Menge Arbeit. Okay, komplexe Konstrukte sollte man in der Implementation schon beschreiben, aber wenn ich doxygen benutze, dann landen diese Beschreibungen im Nirvana. Naja, muss mich da noch bissl einarbeiten...


----------



## jccTeq (15. Oktober 2004)

Okay, so weit so gut. Gibt es irgendein Tool, das einem die Funktionen und Klassen und so auflistet und anzeigt, welche man davon noch nicht dokumentiert hat? Was für weitere Tools kann man für die Effektivitätssteigerung einer Dokumentation von Code noch verwenden? Ich kenn mich da nich so aus. Dokumentiere so selten...


----------



## Mr.Undertaker (15. Oktober 2004)

Also ich bin der Meinung, dass Code nur "gering" zu kommentieren ist. Also nur die nötigen "Kleinigkeiten", wie z.B was der Abschnitt macht und für was diese spezielle Variable da ist. 

Wie die Klassen miteinander agieren, sollte in eine richtige _externe_  Dokumentation. Um so etwas darzustellen, nimmt man ein UML-Diagramm. Tools die UML-Diagramm erstellen sind z.B. Rational Rose, Borland Together oder MS Visio.
Naja, aber auch das sollte man eigentlich vorher machen, da diese Programme ja auch den nötigen Quelltext erstellen können.

Jetzt hab ich wahrscheinlich mehr verwirrt als geholfen, sorry


----------



## canuzzi (15. Oktober 2004)

Also den "inneren" Code zu dokumentieren, halte ich auch fuer sehr wichtig. Schon fuer einen selber, manchmal kann es echt hart sein zu vertsehen was man da so gemacht hat und warum. Da ist ein bischen Kommentar nicht schlecht. Ich habe mir inzwischen auch angewoehnt, zuerst den Kommentar zu schreiben und dann zu coden, dass hilft auch beim Design und der Programmierung. Also Beispielweise:

/* Funktion macht foo */

/* Algorithmus macht bar */

/* Jetze fooe herum bis alles bar */

/* usw. */


----------



## jccTeq (18. Oktober 2004)

UML-Diagramme...jipiieh... naja, sie haben ja ihre Daseinsberechtigung. Aber welche Software benutze ich, wenn es sich bei meinem Programm um ein Linux-Programm handelt, dessen Code ausschließlich mit 'nem Texteditor erstellt wurde. Also komplett by Hand ohne Assistenz-Programme (Visual Studio o.ä.). Was für Doku-Software gibt es da außer doxygen noch?


----------

