Wo Methoden kommentieren
-
Abend,
ne kurze Frage: Wo kommentiert ihr Methoden (also deren Parameter, Rückgabewert und Funktionsweise)? Im Header oder in der Definition (.cpp) Datei? Gibt es da einen gängigen Standard?
Ich habe mit dem Gedanken gespielt die Parameter, Rückgabewerte und Kurzbeschreibung im Header zu platzieren und eine ausführlichere Beschreibung in der .cpp Datei. Allerdings gefällt mir die Aufteilung der Doku auch nicht 100%ig.
Danke
-
Es macht eigentlich mehr Sinn im Header, da man dann als Nutzer nicht in die .cpp rein gehen muss. Was auch sinnvoll ist, wenn es eine Bibliothek ist, da da die .cpp gar nicht zugänglich ist.
Allerdings könnte man das schon in die Quelldatei tun und dann eine generierte Doku mitgeben (z.B mit doxygen).
-
Vorzugsweise im Header. Falls mal jemand Doxygen umgeht, dann ist dies die übliche Anlaufstelle für Informationen über die Schnittstelle. Die Implementierung hat ihn gar nicht zu interessieren, da soll niemals jemand reinschauen. Eventuell liefere ich ja sogar nur Header und vorkompilierte Objektdateien aus*, da sähe man dann gar keine Kommentare mehr.
*: Rein hypothetisch, ich bin Open Source Fan.
-
Ja, so dachte ich mir das auch. Aber ich habe manche Methode, deren Rumpf (Arbeitsweise) absolut nicht trivial ist und deren Code ich ohne genaue Erklärung der Algos wohl in ein paar Monaten selber nicht mehr verstehen würde.
Wie gesagt wollte ich die Doku eigentlich aufsplitten (Parameter, Rückgabewert und kurze Beschreibung im Header; Detailbeschreibung (wenn nötig) im .cpp).
Kann man mit Doxygen eigentlich 2 Dokus erstellen? Eine "Anwender"-Doku, die nur aus den Headerkommentaren erzeugt wird und eine Entwicklerdoku, die auch die ausführliche .cpp Doku mit einbezieht.
-
this->that schrieb:
Ja, so dachte ich mir das auch. Aber ich habe manche Methode, deren Rumpf (Arbeitsweise) absolut nicht trivial ist und deren Code ich ohne genaue Erklärung der Algos wohl in ein paar Monaten selber nicht mehr verstehen würde.
Die Implementierung kommentierst du am besten innerhalb der Funktionsdefinition in der .cpp-Datei. Im Header muss nur stehen, was die Methode macht, und nicht wie sie das macht.
this->that schrieb:
Kann man mit Doxygen eigentlich 2 Dokus erstellen? Eine "Anwender"-Doku, die nur aus den Headerkommentaren erzeugt wird und eine Entwicklerdoku, die auch die ausführliche .cpp Doku mit einbezieht.
Ja, das kannst du mit dem Befehl @cond erreichen (oder mit dem C-Präprozessor).
-
Alles klar.
