XML Comments
-
Tag Leute,
Thema "Quellcode dokumentieren"
ich stehe vor dem Entscheid für einen einheitlichen Doku Stil für Software Projekte. Sprache ist im Moment in VC++, kann aber auch mal was anderes sein (C#, C).
+Punkt:
ich tendiere zum XML Stil, weil es zum einen ein verbreitetes Format darstellt (zwar nicht unbedingt Quellcode Doku).
+Punkt:
Wenn ich das richtig verstanden habe, kann doxygen UND auch VS2008&Sandcastle dieses Format interpretieren.
Also ist man hier unabhängig vom Werkzeug/Generator.-Punkt:
mir persönlich gefällt XML nicht besonders.<param name="strFilePath"></param>ist einfach nicht so leserlich wie
\param [in]->Frage: wie sehr ist die Leserlichkeit im Code überhaupt ein Argument? Schliesslich muss die _Doku_ (formatiert) dann leserlich sein und nicht im code selber oder wie?
gruss
EDIT:
wie haltet ihr es mit dem Ort des Comments?
1. im .h file wird alles beschrieben... und im cpp file steht höchstens noch was von "implementierung"
2. alles ins .cpp file?
3. teils/teils (?)
-
Ich benutze zum dokumentieren das Doxygen/Javadoc Format, weils erstens recht weit verbreitet ist und ich nicht unbedingt mehrere Dukomentationssysteme unterstützen muss. VS2008+Sandcastle sagt mir jetzt nicht so viel, aber da ich eh den Anspruch habe Code nicht nur für MSVC sondern auch für andere Plattformen zu schreiben, muss die Doku auch nicht auf ein Plattformabhängiges System zugeschnitten sein.
Was die Leserlichkeit angeht: Die Doku im Code muss auf jeden Fall leserlich sein. Alles andere würde sowohl Maintainer als auch Entwickler davon abschrecken, ordentlich und ausführlich genug zu dokumentieren. Die Doku würde dadurch wertlos.
Zum Ort der Kommentare:
Dokumentation zum Interface auf jeden Fall im Header, das ist im Grunde auch alles was hinterher von Doxygen extrahiert werden soll. Im Sourcecode selbst nur Hinweise zur Implementierung für spätere Maintainer.
-
Benutze die Javadoc-Syntax die ist sehr leserlich, quasi-Standard und Doxygen unterstützt sie. Und somit bist du für alle Zeit auf der sicheren Seite, denn Doxygen ist jetzt zu diesem Zeitpunkt freie Software und somit wird es für alle Ewigkeiten eine freie Doxygen Software geben, selbst wenn der Autor zukünftige Versionen nur noch kommerziell vertreibt.
-
danke für eure hinweise.
ich muss auch nicht mehrere systeme unterstützen, schaut man jedoch etwas in die zukunft, weiss ich einfach nicht was alles kommt (und geht!).
im moment ists klar nur VS2008/C++ mit doxygen.
mit der wahl von xml comments hätt ich gleich noch die Unabhängigkeit vom Dokusystem mit dabei, auf Kosten der Leserlichkeit.da entscheid ich mich lieber aber für die leserlichkeit und gegen XML
-
^^xml selber schreiben ist doof, aber bestimmt gibt's schon irgendwo ein tool, das aus doxygen-tags xml macht.
-
mathias_f schrieb:
im moment ists klar nur VS2008/C++ mit doxygen.
mit der wahl von xml comments hätt ich gleich noch die Unabhängigkeit vom Dokusystem mit dabei, auf Kosten der Leserlichkeit.Nö, du hättest die Abhängigkeit von Dokusystemen, die Doxygen-Stil verstehen eingetauscht gegen die Abhängigkeit von Dokusystemen, die XML-Tags erstehen, und zwar in genau der Form wie du sie verwendest. Es gibt aktuell vermutlich von beiden Systemen ein oder mehrere aktuelle Kandidaten, aber welches von beiden wird sich wohl auf Dauer durchsetzen? Vermutlich das leserlichere, das Open Source und damit umsonst zu haben ist.
-
+fricky schrieb:
^^xml selber schreiben ist doof, aber bestimmt gibt's schon irgendwo ein tool, das aus doxygen-tags xml macht.
Klar nennt sich regexp
Jetzt mal ehrlich Java-Doc zu "parsen" ist ja wohl kinderleicht, da kann man sich mühelos was mit Perl/Python/... + regexps zusammenbasteln. Aber wie gesagt das wird einfach nie ein Problem sein, denn Javadoc-Style ist quasi-Standard. XML nicht so wirklich ...
-
XML selber schreiben ist wirklich unangenehm. Daher halte ich auch nichts von XML Kommentaren. Wenn es zu unangenehm wird etwas vernünftig zu dokumentieren, dann dokumentiert man es im Zweifelsfall nicht vernünftig. Daher lieber => mehr Komfort.
Zumal ich keinen Vorteil darin sehe die Kommentare als XML zu haben. Im Endeffekt ist das Parsen des Quellcodes die Schwierigkeit und nicht die der Dokumentation und die meisten Tools können im Endeffekt eh XML/Docbook ausgeben.
-
Ich bevorzuge auch doxygen/javadoc/qt/wasauchimmer kommentare. XML in den kommentaren ist irgendwie nichts halbes und nichts ganzes. Vor allem ist es sowieso kein valides XML, mit den gängigen XML tools kommt man da also sowieso nicht zurecht.
Der punkte, warum man für so viele sachen XML einsetzt sind ja die, dass es zum einen immer lesbar bleibt und zum anderen problemlos mit XSLT bearbeitet werden kann.
Lesbar sind und bleiben doxygen kommentare auf jeden fall, mit XSLT kann ich bei xml-kommentaren so erstmal nicht viel ausrichten. Daher: XML in den kommentaren hat null vorteile in meinen augen.