Dokumentieren in C/C++ ?

[Kekeke (Gast)]

Hallo alle zusammen,

wir haben erst nächstes Jahr prozedurale Programmierung mit C im 
Studium. Mich würde aber dennoch bereits interessieren, wie und womit in 
C bzw. C++ der Code dokumentiert wird. Gibt es da einen 
Industriestandard? Ich kenne bislang nur JDoc für Java. Da bieten die 
meisten IDE's ja direkt eine Funktion womit man die per Klick direkt im 
HTML exportieren kann. Wie sieht es da bei C und C++ aus?

Viele Grüße

[Dennis S. (eltio)]

Hallo, Doxygen wäre da eine gute Möglichkeit und wird auch durchaus in 
der Industrie eingesetzt.

[Fritz (Gast)]

Doxygen.

Aber beachte: generierte Dokumentation ist keine Dokumentation.

In der Industrie (und vielen Open-Source-Projekten) macht man das nur, 
weil man keinen Bock auf echte Doku hat, aber trotzdem verpflichtet ist, 
etwas abzuliefern, was als Doku fehlinterpretiert werden kann.

[Kekeke (Gast)]

Vielen Dank für die raschen Antworten! :)

Fritz schrieb:
> Aber beachte: generierte Dokumentation ist keine Dokumentation.

Entschuldigt die Frage, aber wie unterscheiden sich eine generierte 
Dokumentation von einer "anderen"? In JDoc beispielsweise gebe ich doch 
ebenfalls die Beschreibung manuell an und beschreibe die Parameter usw. 
Generiert wird doch dann lediglich eine lesbare Anordnung? Oder verstehe 
ich da was falsch?

Lg!

[Stefan Hennig (Gast)]

Hallo!

Das klingt jetzt neu. Wieso? Meinst Du mit "generierter Dokumentation" 
Doku, die aus nicht instrumentiertem Code erzeugt wird, und einfach 
kommentarlos irgendwelche Aufrufgraphen, etc. aufzeigt?

Wir verwenden Doxygen und schreiben halbe Romane in den Source-Code. 
Bisher hat das keine Probleme gegeben und ich wüsste auch nicht, wieso. 
Wenn Code und Dokumentation aus derselben Quelle stammen, erspart man es 
sich, beides zwangsweise synchron zu halten (ja, ist mit geeigneten 
Prozessen natürlich machbar, aber nur mit zusätzlichem Aufwand, den ich 
irgendjemandem in Rechnung stellen muss).

Die Alternative in der Industrie sind nämlich immer noch häufig 
irgendwelche Word-Vorlagen, und das ist einfach Tierquälerei, einen 
Entwickler zu zwingen die auszufüllen.

Also meine ehrlich gemeinte Bitte: Erkläre doch mal genauer, was Du 
meinst.

Danke,
 Stefan

[Nobody (Gast)]

Du solltest dich auch mit 
http://de.wikipedia.org/wiki/Literate_programming als Grundlage 
beschäfigen.

[Klaus W. (mfgkw)]

Stefan Hennig schrieb:
> Wir verwenden Doxygen und schreiben halbe Romane in den Source-Code.
> Bisher hat das keine Probleme gegeben und ich wüsste auch nicht, wieso.

Ist schon in Ordnung, macht weiter so.

Das wird häufig gemacht und erzeugt (wenn man es ernsthaft betreibt) 
gute Programmierdoku.

Doof ist es nur, wenn man nichts manuell schreibt und nur von einem Tool 
das ausgeben lässt, was sich algorithmisch an Doku erzeugen lässt 
(Parameter auflisten etc.).

Zudem muß man überlegen, für wen man dokumentiert.
Doxygen ist sehr auf die Struktur des Quelltextes fixiert, und damit gut 
geeignet, Doku für Programmierer zu erzeugen.
Dagegen ergibt das natürlich keine Doku für einen weiter entfernt 
stehenden Anwender eines Programms. Z.B. würde sich eine Sekretärin, die 
mit Word arbeiten muß, nicht in einer Doku zurechtfinden, die aus dem 
Quelltext erzeugt wird.
Außerdem kann eine nachträglich erzeugte Doku niemals das ersetzen, was 
man VOR der ersten geschriebenen Zeile Quelltext schon haben sollte, 
nämlich was man eigentlich schreiben will.

[Tom (Gast)]

siehe auch
Beitrag "C Kommentierung in der Praxis"
zu dem Thema gibt es auch noch einige andere Threads.

[Karl H. (kbuchegg)]

Klaus Wachtler schrieb:

> Doof ist es nur, wenn man nichts manuell schreibt und nur von einem Tool
> das ausgeben lässt, was sich algorithmisch an Doku erzeugen lässt
> (Parameter auflisten etc.).

Was leider auch nicht so selten vorkommt.

[Fritz (Gast)]

Genau das meinte ich.

Aber selbst andernfalls: Wirklich gute Dokumentation besteht nicht nur 
aus dem funktionszentrierten Format, das Doxygen geradezu herausfordert.

Größere Projekte brauchen Tutorials, Guides, Handbooks.

Das ist alles eine Frage der Abstraktionsebene und auch "des Tonfalls".

[Tobias K (Gast)]

Alles schon richtig, aber darum geht's doch hier gar nicht:

Doxygen ist das, was der OT sucht. Wenn man so will, das "C++ Pendant zu 
JavaDoc".

Tutorials, Guides, Handbooks, Stories, UseCases, usw. können relevant 
sein, sind jedoch allesamt völlig programmiersprachenagnostisch.

Viele Grüße,
TK