Doxygen, zu schwer für die Wartung? [closed]

Ich fange gerade an, doxygen zu verwenden, um meinen Quellcode zu dokumentieren. Ich habe bemerkt, dass die Syntax sehr schwer ist, jedes Mal, wenn ich den Quellcode ändere, muss ich auch den Kommentar ändern, und ich habe wirklich den Eindruck, zu viel Zeit damit zu verbringen, den Kommentar für jede Änderung, die ich im Quellcode mache, zu ändern.

Haben Sie Tipps, um meinen Quellcode effizient zu dokumentieren?

Gibt es einen Editor (oder ein Plugin für einen vorhandenen Editor) für Doxygen, um Folgendes zu tun?

• nicht synchronisierten Code/Kommentar automatisch verfolgen und den Programmierer davor warnen.
• Fügen Sie automatisch das Doxygen-Kommentarformat (z. B. Vorlage mit Parametername darin) in den Quellcode (Vorlage) für jedes neue Element ein

PS: Ich arbeite an einem C/C++-Projekt.

Ist es die Doxygen-Syntax, die Sie schwierig finden? Oder liegt es daran, dass Sie jetzt alle Funktionen kommentieren müssen.

Wenn es ersteres ist, gibt es möglicherweise ein anderes Tool, das besser zu Ihrem Programmierstil passt. Denken Sie daran, dass Doxygen mehrere Kommentarstile unterstützt, also experimentieren Sie, bis Sie einen finden, der Ihnen gefällt.

Wenn es letzteres ist, dann mach es aus. Als gute Programmierpraxis sollte jede öffentlich zugängliche Funktion einen Kommentarkopf haben, der Folgendes erklärt:

1. Was die Funktion tut
2. Die Parameter
3. Die Rückgabecodes
4. Alle wichtigen Warnungen/Einschränkungen bezüglich der Funktion.

Dies gilt unabhängig vom verwendeten Dokumentationstool.

Mein großer Tipp: Widerstehen Sie der Versuchung, zu viel zu kommentieren. Beschreiben Sie, was Sie brauchen, und nicht mehr. Doxygen gibt Ihnen viele Tags, aber Sie müssen sie nicht alle verwenden.

• Sie brauchen nicht immer einen @brief und eine ausführliche Beschreibung.
• Sie müssen den Funktionsnamen nicht in die Kommentare einfügen.
• Sie müssen den Funktionsprototyp UND die Implementierung nicht kommentieren.
• Sie brauchen den Dateinamen nicht am Anfang jeder Datei.
• Sie brauchen keinen Versionsverlauf in den Kommentaren. (Sie verwenden ein Versionskontrolltool, richtig?)
• Sie brauchen kein “Datum der letzten Änderung” oder ähnliches.

Zu deiner Frage: Doxygen hat einige Konfigurationsoptionen, um Warnungen auszulösen, wenn die Kommentare nicht mit dem Code übereinstimmen. Sie können dies in Ihren Build-Prozess integrieren und die Doxygen-Ausgabe auf Warnungen scannen. Dies ist der beste Weg, den ich gefunden habe, um Abweichungen im Code gegenüber Kommentaren zu erkennen.

Ich habe das Gefühl, dass Sie das zurückbekommen, was Sie in Kommentare geschrieben haben. 5 Minuten, um eine Klasse zu kommentieren, werden in 3 Monaten viel weniger Zeit in Anspruch nehmen, wenn die Klasse von jemand anderem als dem ursprünglichen Autor (tatsächlich manchmal vom ursprünglichen Autor) geändert werden muss in den Griff zu bekommen.

Ich unterstütze die von David erwähnte Dokumentationsunterstützung. Wenn Sie in Eclipse Parameternamen umgestalten, wird der Parameter beispielsweise in Ihrem Dokumentabschnitt umbenannt. Ich bin mir nicht sicher, ob ich möchte, dass es automatisch irgendetwas anderes tut, um ehrlich zu sein.

“Jedes Mal, wenn ich den Quellcode ändere, muss ich auch den Kommentar ändern” Möglicherweise dokumentieren Sie zu viel. Sie sollten die Dokumentation einer Funktion nur dann ändern müssen, wenn die Änderung es erfordert, dass Sie jeden Aufrufer in irgendeiner Weise ändern (oder wenn nicht tatsächlich ändern, zumindest überprüfen, ob sie sich nicht auf veraltetes Verhalten verlassen), oder wenn Sie führen neue Funktionen ein, auf die sich ein neuer Anrufer verlassen wird. Theoretisch sollte es also kein massiver Overhead sein. Kleine Änderungen, wie Optimierungen und Bugfixes innerhalb der Funktion, müssen normalerweise nicht dokumentiert werden.

Es ist ernsthaft etwas falsch an der Art und Weise, wie Sie Kommentare verwenden oder wie Sie sich entwickeln.

Doxygen-Kommentare dienen der externen/internen Dokumentation von Schnittstellen. Wenn sich Ihre Schnittstellen extrem schnell ändern, sollten Sie sich wahrscheinlich zuerst hinsetzen und über das Architekturlayout nachdenken.

Wenn Sie doxygen verwenden, um den internen Ablauf von Funktionen zu dokumentieren, sollten Sie diesen Ansatz vielleicht überdenken (und selbst dann sollten sich diese Kommentare nicht so sehr ändern). Wenn Sie eine Funktion haben, die einen Wert berechnet, dann einen Kommentar /// Calculating xy using the abc algorithm ist definitiv etwas, das sich nicht jeden Tag ändern sollte.

Es hängt wirklich davon ab, wie viele Informationen Sie in Ihre Dokumentation aufnehmen.

Meine Funktionen sind aufgrund von Unit-Tests jetzt generell kleiner geworden und dementsprechend klein ist auch die Dokumentation. Auch wenn ich die Klasse selbst dokumentiere, habe ich immer einen kleinen Codeausschnitt, um zu zeigen, wie die Klasse verwendet werden soll. Ich finde, diese sind am schwierigsten zu warten, aber es lohnt sich, damit Sie nicht von Junioren genervt werden, die Sie fragen, wie sie die Klasse verwenden.

Tipps:

• Dokumentieren Sie nur Ihre öffentlichen Schnittstellen.
• Machen Sie nur eine minimale Dokumentation darüber, was die Funktion tut.
• Versuchen Sie, einen Editor zu verwenden, der Unterstützung bietet (die meisten tun dies) oder ein Plugin hat.

Sie werden froh sein, wenn Sie in 6 Monaten kommen, um Ihren Code zu bearbeiten …

Beurteilen Sie selbst, ob der untenstehende Stil Ihren Bedürfnissen entspricht. Es ist zwar C-affin, aber vielleicht kannst du daraus genug für deine Zwecke ziehen.

///\file

/// Brief description goes here
bool /// @retval 0 This is somewhat inconsistent. \n Doxygen allows several retval-descriptions but 
     /// @retval 1 will not do so for parameters. (see below)
PLL_start( 
   unsigned char busywait, ///< 0: Comment parameters w/o repeating them anywhere. If you delete this param, the
                           ///     comment will go also. \n
                           /// 1: Unluckily, to structure the input ranges, one has to use formatting commands like \\n \n
                           /// 2-32767: whatever
   int param)              ///< 0: crash \n
                           ///  1: boom \n
                           ///  2: bang!
{
   /**
    * Here goes the long explanation. If this changes frequently, you have other more grave problems than 
    * documentation. NO DOCUMENTATION OF PARAMETERS OR RETURN VALUES HERE! REDUNDANCY IS VICIOUS!
    * - Explain in list form.
    * - It really helps the maintainer to grok the code faster.
    *
    *@attention Explain misuses which aren't caught at runtime.
    *
    *@pre Context:
    * - This function expects only a small stack ...
    * - The call is either blocking or non-blocking. No access to global data. 
    *
    *@post The Foobar Interrupt is enabled. Used system resources:
    *    - FOO registers 
    *    - BAR interrupts
    */
    /**@post This is another postcondition. */
}

Verwenden Sie nicht dokumentierende Kommentare für neue Funktionen und frühe Phasen Ihres Codes. Wenn Sie feststellen, dass Ihr Code zur Veröffentlichung bereit ist, können Sie die Dokumentation aktualisieren. Vermeiden Sie auch die Wiederholung von Argument- oder Funktionsnamen.

Nutzen Sie die Stärken von Doxygen – es generiert Klassen- und Methodenbeschreibungen, ohne dass Sie Kommentare hinzufügen (nur nicht standardmäßig – setzen Sie EXTRACT_ALL=YES).

Ich dokumentiere nicht jeden Parameter, weil ich denke, dass ihre Namen das für sie tun sollten

.

Ich bin gegen die Autodokumentations-Plugins, die die meisten Leute empfehlen, weil sie allgemeine Kommentare erstellen, die Sie dann pflegen müssen.

Ich möchte, dass Kommentare aussagekräftig sind – wenn ich einen Kommentar sehe, fällt er auf und ich werde darauf achten.