Dokummentation und Zuweisungsoperator

xorm

Huhu,
ich hätte mal 2 Fragen:

Die erste ist bezüglich Dokumentation. Wie dokumentiert man vernünftig eine C++ Klasse?
Sicher kann man kommentieren wie man will.. mich interessiert in der Hinsicht allerdings wie das bei großen Projekten und/oder von Firmen gehandhabt wird. Mir fehlt es bei C++ an praktischer Erfahrung, möchte es mir aber gleich von Anfang an 'vernünftig' angewöhnen. Ich tendiere im Moment dazu Beschreibungen von Klassen und Methoden in die Header Datei zu schreiben, da diese ja praktisch die Schnittstelle ist. Beschreibung von interner Funktionalität schreibe ich bisher allerdings in die .cpp Datei.

Bei der zweiten Frage geht es um den Zuweisungsoperator. Ich habe eine Klasse die sich um die Organisation von bestimmten Abläufen kümmert. Die Implentierung des Zuweisungsoperators würde bei dieser Klasse definitv keinen Sinn machen. Zuerst wollte ich aus der Klasse ein Singleton machen allerdings bin ich davon abgekommen da es durchaus möglich wäre unterschiedliche Instanzen der Klasse an verschiedenen Stellen zu nutzen. Gibt es eine Möglichkeit den Zuweisungsoperator für bestimmte Klassen zu 'verbieten'? Oder gibt es eine andere Möglichkeit mit sowas umzugehen?

BorisDieKlinge

1.)
würde alle Kommentare in die Header machen.. was in den funktionsrumpf selber passiert natürlich in den CPP! Schau dir mal latex an!

2.) überschreib einfach den zuweisungoperator

const KLASSE& KLASSE::operator=(const KLASSE &oScr){
  assert(false);
  return *this;
};

so werden keine daten des Quellobjelt übernommen.. aber verbieten direkt geht nich!
denk noch an dne Kopykonstruktor

DeSoVoDaMu

Hi,
um den Zuweisungoperator zu verbieten musst du ihn nur privat deklarieren. Zusaetzlich sollte er nicht definiert werden, damit ein (moeglicherweise vorkommender) Aufruf aus der Klasse selbst spaetestens beim Linken zu einem Fehler fuehrt.

Dokumentieren kannst du Klassen ansich wie du willst. Mir ist auch keine wirkliche Richtlinie bekannt, an die sich groessere Projekte halten (habe mich aber auch noch nicht weiter damit beschaeftigt).
Ich halte nicht viel davon die Methoden in der Headerdatei bei der Deklaration zu kommentieren. Ich dokumentiere Funktionen bei der Definition. Ist aber geschmackssache.
Zusaetzlich gibt es Programm wie Doxygen, die ein gewisses Format des Kommentares voraussetzen und dann HTML-, Latex- oder aehnliche Dokumentationen daraus erstellen - imho ganz praktisch.

Gruss,
DeSoVoDaMu

BorisDieKlinge

um den Zuweisungoperator zu verbieten musst du ihn nur privat deklarieren. Zusaetzlich sollte er nicht definiert werden, damit ein (moeglicherweise vorkommender) Aufruf aus der Klasse selbst spaetestens beim Linken zu einem Fehler fuehrt.

ups..stimmt ja;)

.filmor

xorm schrieb:

Ich tendiere im Moment dazu Beschreibungen von Klassen und Methoden in die Header Datei zu schreiben, da diese ja praktisch die Schnittstelle ist. Beschreibung von interner Funktionalität schreibe ich bisher allerdings in die .cpp Datei.

Mach ich auch so. Ich schätze, das ist gängige Praxis. Du solltest dir vielleicht doxygen ansehen. Wenn du "dafür" dokumentierst hast du quasi automatisch einen anständigen Stil.

xorm schrieb:

Gibt es eine Möglichkeit den Zuweisungsoperator für bestimmte Klassen zu 'verbieten'? Oder gibt es eine andere Möglichkeit mit sowas umzugehen?

Allgemein macht man das so, in dem man selbst einen Zuweisungsoperator im privaten Bereich deklariert. Implementieren muss man ihn nicht, da er ja gar nicht böswilligerweise benutzt werden kann.

class MeineKlasse
{
private:
    MeineKlasse& operator= (MeineKlasse const&);
};

Wenn die Instanzen allgemein nicht kopierbar sind (also auch der Kopierkonstruktor nicht sinnvoll ist) und du Boost benutzt, dann kannst du einfach privat von boost::noncopyable aus <boost/utility.hpp> ableiten. (Wenn dir Boost zu "fett" ist, dann kannst du auch nur den entsprechenden Header kopieren).

thordk

xorm schrieb:

Ich tendiere im Moment dazu Beschreibungen von Klassen und Methoden in die Header Datei zu schreiben, da diese ja praktisch die Schnittstelle ist. Beschreibung von interner Funktionalität schreibe ich bisher allerdings in die .cpp Datei.

der sinn und zweck eines kommentares ist es, die schnittstelle zu beschreiben. sinn, tätigkeit und daseinsberechtigung. warum gibt es diese klasse, was macht sie und welche bedingungen stellt sie bei verwendung. die innereien einer klasse (implementierung) sind weniger interessant. deshalb gehört ein kommentar immer zur deklaration, sprich in den header, nicht zur implementierung. wenn es einige wichtige details zur implementierung gibt, kann man sie auch dazuschreiben. z.b. wenn für eine konkrete implementierung ein bestimmter sortieralgorithmus verwendet wird, der bei schlechten vorbedingungen dazu führen kann, dass manche methoden abnormal lange benötigen. ansonsten gehören implementierugnsdetails aber nicht in den kommentar einer schnittstelle.

beispiel:

/**
 * Liefert den anteil von src bis zum ersten vorkommen von token.
 */
string str(string src, char token);
// kurz und prägnant

/**
 * Iteriert über alle chars von src und vergleicht sie mit token. Bei
 * ungleichheit wird der char an einen temporären string angehängt, der
 * schlussendlich zurückgegeben wird.
 */
string str(string src, char token);
// blödsinnige details ;)

xorm

Oki.. vielen Dank

Badestrand

Kennt jemand gut kommentierten Quellcode? Alles was ich immer sehe ist sowas:

// Specifies whether the data is empty
bool is_empty();

Oder so. Und das finde ich relativ nervig. Ich bin jedenfalls der Meinung, dass man bei sehr gut gewählten Bezeichnern und gutem Design die Header-Dateien auch ohne Kommentare verstehen kann - in der Regel jedenfalls, bei spezielleren Sachen wohl nicht. Naja, und ob ich mich durch HTML-Dateien oder Source-Code klicke ist mir letztlich auch egal (nagut, nicht ganz ;)).

HumeSikkins

Badestrand schrieb:

Kennt jemand gut kommentierten Quellcode? Alles was ich immer sehe ist sowas:
// Specifies whether the data is empty
bool is_empty();
Oder so. Und das finde ich relativ nervig.

Ist es auch, aber das Ziel von Dokus ist es eigentlich auch nicht den Quelltext zu beschreiben, denn der sollte sich selbst beschreiben. Gut lesbarer Quelltext ist in der Regel aber nicht genug, denn Dinge wie Pre-/Post-Conditions, Angaben zur Komplexität einer Operation, Ausnahmesituationen (welche Exceptions werden geworfen und wann), Designentscheidungen usw. lassen sich über den Quelltext nicht mehr so einfach nachvollziehen. Hier hilft eine gute Doku dann ungemein.