Wo kommentiert ihr Funktionen?



  • Wo kommentiert ihr Funktionen?

    Bei der Deklaration in der Header Datei oder in der Source Datei?

    Ich meine jetzt Kommentare, die über einer Funktion stehen und kurz beschreiben sollen, was diese macht. Kommt jetzt bitte nicht mit Sprüchen wie "gib deiner Funktion lieber einen gescheiten Namen", ich bin ja auch nicht auf dem Kopf gefallen 😋



  • Bei der Implementation machen längere Dokus mehr Sinn, weil man dann direkt zwischen Code und Beschreibung vergleichen kann. In der header-Datei sollte man m.E. eine Übersicht erhalten über die Vielzahl der Funktionen; da stören längere Kommentare eher.



  • Ich finde es sinnvoller die Beschreibung im Header anzubringen, Grund:

    Ich will's ja nur benutzen und nicht in die Implementierung reinschaun. Da sollte ein Blick in den Header genügen.

    In die Implementierungsdatei gehört dann eher die Beschreibung wie eine Funktion ihre Aufgabe löst und wenn es mehrere Möglichkeiten gab, warum diese Implementierung gewählt wurde.

    MfG Jester



  • Jester schrieb:

    Ich will's ja nur benutzen und nicht in die Implementierung reinschaun. Da sollte ein Blick in den Header genügen.

    Oder in die automatisch per doxygen generierte Doku; ich hasse mit Kommentaren zugemüllte Header!



  • nman schrieb:

    Jester schrieb:

    Ich will's ja nur benutzen und nicht in die Implementierung reinschaun. Da sollte ein Blick in den Header genügen.

    Oder in die automatisch per doxygen generierte Doku; ich hasse mit Kommentaren zugemüllte Header!

    Da mußt du die Doku aber auch irgendwohin schreiben und ich schreibe die Doxygen Kommentare wiederum in die Header da ich für mehr Übersicht in den Implementationsdateien bin und man somit zur Not immer noch was lesen kann wenn man nur die Header zur Verfügung hat. Na ja, meiner Meinung nach spielt da viel persönlicher Gusto mit.

    Joe



  • JoeIntel schrieb:

    Na ja, meiner Meinung nach spielt da viel persönlicher Gusto mit.

    Da stimme ich Dir völlig zu. 👍

    (Ich habe die Header halt gerne schön kurz und übersichtlich weil man bei gut designten Klassen teils die Doku gar nicht so genau lesen zu braucht wenn die verwendeten Namen halbwegs sinnvoll sind.)



  • So:

    /******************************************************************************/
    /*                                                                            */
    /* functionname: CHashTable()                                                 */
    /* description:  Constructor der Klasse CHashTable, initialisiert die         */
    /*               Hashtabelle und schreibt schon vorhandene Tokens in die      */
    /*               Tabelle                                                      */
    /* returns:      nothing                                                      */
    /* input:        nothing                                                      */
    /* output:       nothing                                                      */
    /*                                                                            */
    /******************************************************************************/
    CHashTable::CHashTable()
    {
    	//vordefinierte Tokens in die Hashtabelle eintragen
    	Insert("class", 5);
    	Insert("end", 3);
    	Insert("var", 3);
    }
    

    und zwar im Code, in den Header-Files komentiere ich nur die Variablen, defines, etc.



  • Dito, nur gestalte ich meine Funktionsbeschreibungen etwas spartanischer:

    // Kodiert len Bytes ab Zeiger val nach dem Base64-Verfahren
    // val:		Wert als (unkodierte) Binaerdaten
    // len:		Menge der Binaerdaten in Bytes
    // return:	Zeiger auf Base64-kodierte Daten
    auto_ptr<char> Node::encode_b64(const unsigned char *val, int len)
    {
    }
    


  • Cocaine schrieb:

    Dito, nur gestalte ich meine Funktionsbeschreibungen etwas spartanischer:

    // Kodiert len Bytes ab Zeiger val nach dem Base64-Verfahren
    // val:		Wert als (unkodierte) Binaerdaten
    // len:		Menge der Binaerdaten in Bytes
    // return:	Zeiger auf Base64-kodierte Daten
    auto_ptr<char> Node::encode_b64(const unsigned char *val, int len)
    {
    }
    

    Das ist so ein Beispiel wo meiner Meinung bessere Namen den Kommentar deutlich hätten verkürzen können. Wählt man statt val und len sprechende Namen, kann man auf die Kommentare zu val und len verzichten. Und verwendet man statt b64 gleich base64, gibt's auch hier keine Probleme. Statt dessen wäre imo ein Kommentar, der z.B. die Vor- und Nachbedingungen dieser Methode spezifiziert deutlich hilfreicher.



  • Also offenbar hat doch die Mehrzahl die Funktion bei der Implementation kommentiert. Ich finde die Argumente von beiden Seiten ziemlich einleuchtend, aber ich hab kein Bock, das doppelt zu kommentieren.

    /* Prüft, ob die Strecke, gegeben aus den ersten beiden Punkten,
     * die Box, gegeben aus dem dritten Punkt und dem "Radius", schneidet.
     */
    bool Point2D::segmentIntersectsSquare(const Point2D &point1, const Point2D &point2, const Point2D &middle, __int64 radius)
    {
    	// Erstmal prüfen, ob die Strecke dem Quadrat überhaupt nahe kommt:
    	if (middle.getDistanceToSegmentSquare(point1, point2) > 2 * radius * radius)
    		return false;
    
    	const __int64 left		= middle.x - radius;
    	const __int64 top		= middle.y - radius;
    	const __int64 right		= middle.x + radius;
    	const __int64 bottom	= middle.y + radius;
    
    	// Für alle vier Kanten prüfen, ob die Strecke sie schneidet:
    	// Obere Kante:
    	if( segmentsIntersect(point1, point2, Point2D(left, top), Point2D(right, top)) )
    		return true;
    	// Rechte Kante:
    	if( segmentsIntersect(point1, point2, Point2D(right, top), Point2D(right, bottom)) )
    		return true;
    	// Untere Kante:
    	if( segmentsIntersect(point1, point2, Point2D(left, bottom), Point2D(right, bottom)) )
    		return true;
    	// Linke Kante:
    	if( segmentsIntersect(point1, point2, Point2D(left, top), Point2D(left, bottom)) )
    		return true;
    
    	return false;
    }
    

    Mein Standard zur Zeit. Meine Überlegung ist halt, dass man in der Klasse anhand des Rückgabetyps und des Methodennamens erkennen können sollte, was die Funktion macht. Für eine genauere Beschreibung kann man dann in der Implementation nachsehen. Ich weiß aber selber nicht, was ich davon halten soll 🙄



  • Ich gebe in den Headern ne Überschrift, beschreibe genau in der Implementation und schreibe meistens noch ne Doku (wenn andere Programmierer den Code auch noch benutzen sollen).

    mfg
    Glamdring



  • Also ich verwende seit geraumer Zeit doxygen (www.doxygen.org).


Log in to reply