Du bist nicht angemeldet.

Werbeanzeige

Julién

Alter Hase

  • »Julién« ist der Autor dieses Themas

Beiträge: 713

Wohnort: Bayreuth

Beruf: Student | Hilfswissenschaftler in der Robotik

  • Private Nachricht senden

1

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

1
2
3
4
5
6
7
8
9
10
11
12
13
/// <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

Sylence

Community-Fossil

Beiträge: 1 650

Beruf: Softwareentwickler

  • Private Nachricht senden

2

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.

Sacaldur

Community-Fossil

Beiträge: 2 280

Wohnort: Berlin

Beruf: FIAE

  • Private Nachricht senden

3

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)
---
Es ist ja keine Schande etwas falsch zu machen, als Programmierer tu ich das täglich, [...].

Julién

Alter Hase

  • »Julién« ist der Autor dieses Themas

Beiträge: 713

Wohnort: Bayreuth

Beruf: Student | Hilfswissenschaftler in der Robotik

  • Private Nachricht senden

4

09.11.2019, 17:23

Vielen Dank für eure Antworten!
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

Werbeanzeige