C++ | Wie Implementierung richtig dokumentieren/kommentieren? - C, C++, C#, Java und andere Programmiersprachen

C++ | Wie Implementierung richtig dokumentieren/kommentieren?

Werbeanzeige

Julién

Alter Hase

Beiträge: 717

Wohnort: Bayreuth

Beruf: Student | Hilfswissenschaftler in der Robotik

07.11.2019, 02:23

C++ | Wie Implementierung richtig dokumentieren/kommentieren?

Einen schönen Abend euch allen!

Im Moment überarbeite ich meine Library und möchte diese etwas besser dokumentieren.
Ich präsentiere folgenden Fall:

C-/C++-Quelltext

/// <summary>
/// Die Klasse ist stellt dies und das dar...
/// </summary>
class interface {
  public:

    /// <summary>
    /// Beschreibe das Verhalten der Methode und etc.
    /// </summary>
    virtual void methode1() = 0;
 
    // ...
};

Nun, die Klasse oben ist eine abstrakte Klasse und Nutzer meiner Library werden i.d.R. sich nur mit diesem Interface auseinandersetzen, wobei Instanzen von meiner Library erzeugt werden.
Gelegentlich wird es jedoch vorkommen, dass man mit der Implementierung direkt arbeiten muss.

Die Frage ist nun, wie würde ich die Implementierung korrekt dokumentieren, wenn man bedenkt, dass das Interface eigentlich schon das Verhalten komplett dokumentiert?
Gibt es da eine Art "Konvention" der ich folgen kann? Hat jemand zufällig ein Beispiel parat für eine "gute" Dokumentation einer Implementierung eines Interfaces?

MfG Julién

I write my own game engines because if I'm going to live in buggy crappy filth, I want it to me my own - Ron Gilbert

Zum Seitenanfang

Sylence

Community-Fossil

Beiträge: 1 663

Beruf: Softwareentwickler

07.11.2019, 10:05

Für die Methoden: Gar nichts an Dokumentationskommentaren dran machen.
Wenn es Besonderheiten gibt, dann in der Dokumentation der Implementierungsklasse.

Den Rest sollte die IDE erledigen.

Zum Seitenanfang

Sacaldur

Community-Fossil

Beiträge: 2 301

Wohnort: Berlin

Beruf: FIAE

07.11.2019, 11:45

Was Sylence schreibt.
Der Zweck der Schnittstelle ist es ja zu definieren, wie sich Implementationen im Groben verhalten sollen (bspw. Listen: speichern von Elementen). Sollte aus der Implementation heraus wieder etwas besonders zu beachten sein, dann wäre ein entsprechender Hinweis in der Dokumentation erforderlich.

Spieleentwickler in Berlin? (Thema in diesem Forum)
---