Wie kommentiert ihr?

[Gelöschter Benutzer]

Jetzt muss ich doch mal glatt aufn Klammerthread fragen wie ihr eigentlich kommentiert.

Ich mach das immer so, sofern ich nicht mit Doxygen arbeite:

Code: Alles auswählen

// BS Engine 4 Game Library
namespace BSE4
{
    // Handles a DirectX 10 device
    class Device
    {
        // Creates a device
        const BSError Create(const BSE4Struct::DeviceConfigDesc &CDesc, // The config desc
                             const HWND hWnd /* Handle to a window */ );
    }
}

Arbeite ich mit Doxygen kommentiere ich so:

Code: Alles auswählen

/*! @namespace BSE4
    @brief BS Engine 4 Game Library */
namespace BSE4
{
    /*! @class Device
        @brief Handles a DirectX 10 device */
    class Device
    {
        /*! @brief Creates a device
            @param CDesc is a configuration desc by BSE4Struct::DeviceConfigDesc
            @param hWnd is a handle to a window from a windows Win32 application */
        const BSError Create(const BSE4Struct::DeviceConfigDesc &CDesc,
                             const HWND hWnd );
    }
}

Code: Alles auswählen

    ...
    // Create simple terrain grid
    for(...)
        for(...)
    ...

    /* Here is something to note:
         - ...
    */
    ...

Einige Fälle möchte ich aus Vielseitigkeit jetzt nicht weiter zeigen. Es gibt auf jeden fall mehr Situationen.

Und wie schaut es bei euch aus? Schreibt ihr in Deutsch oder Englisch? Beachtet ihr die 90 Zeichen pro Zeile maximal zum Ausdrucken? :?:

[dowhilefor]

Ich mag das C# Visual Studio Feature ... 3 mal / und ich bekomme automatisch passend zur Zeile einen Block den ich nur noch ausfüllen muss. Eine Abart von XML dürfte das sein.
Ansonsten gibts da nix groß was ich beachte, Kommentare halt solang wie sie sein müssen, wobei ich da meistens meinen Monitor als Maß nehme, nicht eine feste Zeilenbreite.
Grausig finde ich nur wenn Leute /* */ für Kommentare nehmen .

Ein Kollege hat mir noch von einem interessanten Konzept erzählt, er meinte jemand der seinen Code, nicht seine Interfaces, kommentiert hat schlechten Code geschrieben. Zuerst fand ich das unsinnig, aber nach und nach kann ich es nachvollziehen. Wenn ein Code kommentiert werden muss, hätte man ihn umschreiben oder in eine Methode auslagern können, wodurch er an sich klarer wird. Nochmal gemeint ist nicht der Header oder die Klassendefinition sondern die Implementierung.

[Alexander Kornrumpf]

Wie heißt es so schön, ein Kommentar sollte ausdrücken, warum der Code da steht, nicht was er macht (das wäre redundant).

[Seraph]

Das klingt fuer mich zu sehr verallgemeinert. Auch wenn ich selbst kein Fan von von Kommentaren in der eigentlichen Implementierung bin, da es den Lesefluss des Codes stoert und wie Alex schon sagte, es zumeist eh redundant ist, so gibt es immer noch genuegend Faelle wo es durchaus Sinn macht einen Algorithmus kurz zu erklaeren.

Zur eigentliche Frage muss ich mich Nico anschliessen, ich mag /* */ Kommentare nicht, zumal einen das im schlechtesten dann Fall daran hindern kann, einfach mal eben einen Codeblock auszukommentieren.

[Stefan Zerbst]

Ein Kollege hat mir noch von einem interessanten Konzept erzählt, er meinte jemand der seinen Code, nicht seine Interfaces, kommentiert hat schlechten Code geschrieben. ... Wenn ein Code kommentiert werden muss, hätte man ihn umschreiben oder in eine Methode auslagern können, wodurch er an sich klarer wird.

Das ist durchweg interessant aber schlichtweg falsch :twisted:

Wenn man in größeren, kommerziellen Softwareprojekten arbeitet trifft man durchaus auf Stellen in Implementierungen die erklärungsbedürftig sind. Und erschreckenderweise sind das eben nicht große, langwierige Implementierungen, sondern Ein- oder Zweizeiler deren Notwendigkeit sich eben nicht durch den Algorithmus selbst ergibt. Vielmehr ist das was ich jetzt mal Framework nennen möchte der Grund dafür, dass der eine oder andere Aufruf sein muss der States hier oder da setzen muss damit irgendetwas das tun kann was es tun soll.

Hier mag man argumentieren, dass dann etwas am Framework falsch ist oder sich vom Design her zumindest in Teilen selbst überlebt hat. Im Elfenbeinturm ist das dann absolut korrekt, aber in der Realität eines Softwareentwicklers würde der Umbau eines solchen Frameworks locker mal 4 bis 8 Wochen 2 - 4 Arbeitskräfte binden und den Rest des Teams gleichzeitg hart ausbremsen.

Von daher weigere ich mich Code zu peeren dem an solchen Einzeilern der Kommentar fehlt und bin jedem Peer dafür dankbar wenn er mich auf fehlenden Kommentar bei so etwas hinweist :)

@Topic
Doxygen ist klar, da brauchen wir nicht drüber zu reden. Ich habe allerdings die lästige Angewohnheit direkt in den Klassen-Deklarationen die Methoden zu kommentieren was den Header relativ unübersichtlich macht. Schöner ist es diese Kommentare für Doxygen mit @fn in der cpp zu erledigen. Das hat aber zwei Nachteile: Zum einen vergisst man dann oft den Kommentar anzupassen wenn man eine Methode ändert und zum anderen zeigt Eclipse sie dann nicht als QuickInfo an wenn man auf einem Methodenaufruf schwebt.

Im Code mache ich immer da Kommentare wo ich es für nötig halte. Um wieder auf obigen Kollegen zurückzukommen: Es ist nicht jeder ein Fachmann auf allen Gebieten und wenn ich Algorithmen lesen muss die von Mathematikern oder Physikern kommen verstehe ich sonst nur Bahnhof oder brauche erstmal eine Stunde mich da reinzudenken was dort passiert. Ähnlich geht es wohl dem Mathematiker oder Physiker wenn er meinen Grafik-Code sieht :mrgreen: Von daher ist kurzes, prägnantes Kommentieren absolutes Muss.

Es gibt auch Situationen in denen ich mehrzeiligen Kommentar in einer Implementierung für sinnvoll halte. Ein Beispiel für den o.g. Kollegen: Bugs in Qt. Wenn jemand meinen Workaround Code sieht dann wird er denken Warum macht der das so kompliziert, da könnte man doch Methode xyz aus Qt für benutzen .... Und genau an solchen Stellen braucht es einen mehrzeiligen Kommentar warum das so ist, welchen externen Bug es umschifft und ob es z.B. schon eine Ticket-Nummer bei Qt dafür gibt.

Hier oute mich aber auch als /* */ Kommentierer weil ich das bei mehrzeiligen Kommentaren für übersichtlicher halte. Ich komme ehrlich gesagt auch sehr selten in Situationen wo ich ganze Blöcke ausklammern muss. Das tut man meiner Meinung nach nur, wenn man den Code gerade aktiv entwickelt und in einer solchen Situation hat man einen abschließenden Kommentar eh noch nicht geschrieben ;)

Ciao,
Stefan

[eXile]

Ein Kollege hat mir noch von einem interessanten Konzept erzählt, er meinte jemand der seinen Code, nicht seine Interfaces, kommentiert hat schlechten Code geschrieben. ... Wenn ein Code kommentiert werden muss, hätte man ihn umschreiben oder in eine Methode auslagern können, wodurch er an sich klarer wird.

Das ist durchweg interessant aber schlichtweg falsch :twisted:

Wenn man in größeren, kommerziellen Softwareprojekten arbeitet trifft man durchaus auf Stellen in Implementierungen die erklärungsbedürftig sind. Und erschreckenderweise sind das eben nicht große, langwierige Implementierungen, sondern Ein- oder Zweizeiler deren Notwendigkeit sich eben nicht durch den Algorithmus selbst ergibt. Vielmehr ist das was ich jetzt mal Framework nennen möchte der Grund dafür, dass der eine oder andere Aufruf sein muss der States hier oder da setzen muss damit irgendetwas das tun kann was es tun soll.

Hier mag man argumentieren, dass dann etwas am Framework falsch ist oder sich vom Design her zumindest in Teilen selbst überlebt hat. Im Elfenbeinturm ist das dann absolut korrekt, aber in der Realität eines Softwareentwicklers würde der Umbau eines solchen Frameworks locker mal 4 bis 8 Wochen 2 - 4 Arbeitskräfte binden und den Rest des Teams gleichzeitg hart ausbremsen.

Im lezten Semester hat uns ein Dozent gesagt, wenn wir sogenannte "Non-Rationale"-Kommentare verfassen - d.h. einfach nur sagen, was der Code macht, und nicht, wieso die implementierung so gewählt wurde - man das Extract-Method-Refactoring anwenden soll. Dann haben wir uns einen Spaß draus gemacht und in einer anderen Vorlesung unsere Tutoren zur Weißglut gebracht, indem wir unsere Assemblerprogramme in mehrere hundert Funktionen zerstückelten :lol:

Nun mal im Ernst (nämlich das obiges natürlich nur auf Hochsprachen zutrifft). Wir haben uns stark gewundert, als unser Dozent das mit dem Extract-Method-Refactoring sagte. Da wurde sozusagen ein ganz mechanisches Vorgehen propagiert: Wenn man einen Non-Rationale-Kommentar schreibt, dann haben wir bereits damit den Funktionennamen für die extrahierte Funktion gefunden. Wenn dann weiterhin Erklärungsbedarf besteht: Weiteren Kommentar hin, wieder Extract-Method-Refactoring. Und weiter ... hoffentlich nicht ad infinitum. ;)

Der einzige Nachteil der sich daraus ergibt, ist wohl ein ganzer Haufen an neuen Funktionen - das mag auch schon unübersichtlich sein. Aber prinzipiell sehe ich da keine Hindernisse, schließlich stecken alle Kommentare damit in Funktionennamen und der Informationsgehalt ist konstant. Dafür kriegt man eine feinmodularere Unterteilung. Vielleicht magst ja sagen, was du genau an diesem Vorgehen auszusetzen hast - ich bin sozusagen im "Elfenbeinturm" grad drin ;)

PS: Ich benutze immer die C++-Stil-Kommentare, d.h. mit "//". Wahrscheinlich auch aus Faulheit, da ich dann nur zweimal dieselben Tasten drücken muss ;)

[Stefan Zerbst]

Hi,

wie gesagt, es sind gerade die Einzeiler die Kommentar erfordern und dann insbesondere mehrzeiligen Kommentar. Die kann man schlecht in Methoden auslagern ;)

Zudem bringt ein Methodenaufruf gerne auch Overhead mit sich. Da mag man nun argumentieren, dass das kaum meßbar ist aber wir bewegen uns hier in Bereichen die durchaus 100k bis 10000k mal durchlaufen werden und da kommt es auf jedes noch so kleine Milisekundenbruchteilchen an.

Prinzipiell stimme ich aber dem Grundgedanken zu, dass man seinen Code immer dann in mehrere Methoden aufsplitten sollte wenn er zu lang wird. Und dann ersetzen die Methodennamen tatsächlich einzeilige Kommentare. Ich hasse sowieso Methoden die länger sind als auf eine Bildschirmhöhe draufpaßt, auch wenn sich das manchmal nicht vermeiden läßt. Lange Rede, kurzer Sinn: Wenn ein Codeblock der einen einzeiligen Kommentar braucht eine eigene Methode verdient dann bin ich auch für das auslagern.

Aber wie gesagt, leider sind die wichtigen Kommentare oftmals die Art von Kommentaren die nicht in eine Zeile und damit nicht in einen Methodenanmen passen.

Ciao,
Stefan

[kkrahl]

Ich arbeite auch mit doxygen und da das ding auch C# comments nimt arbeite ich mit denen. Sieh wie folgt dann aus:

Code: Alles auswählen

/// <summary> Beschreibung </summary>
/// <param name="parameter"> Parameterbeschreibung </param>
/// <returns> Returnwertbeschreibung </returns>

mfg

Karl

[Jörg]

Zudem bringt ein Methodenaufruf gerne auch Overhead mit sich....

Das Argument zieht nur noch bei "aelteren" Toolchains. Globale Optimierungen sollten genauso gut funktionieren
wie "manuelles" inlinen. Ich wuerde es nicht der Strukturierung opfern, es sei denn das Projekt ist in der Endphase
und es stellt sich heraus, dass die Toolchain versagt. Dann kann man die wirklichen Hotspots noch immer separat
behandeln.

ich mag /* */ Kommentare nicht, zumal einen das im schlechtesten dann Fall daran hindern kann, einfach mal eben einen Codeblock auszukommentieren.

Ja wenn man das einmal gemerkt hat, warum den Code dann nicht ueber #if 0 - #endif deaktivieren? Da hat man sogar die Moeglichkeit, via #if 0 #else #endif Alternativen zu probieren, IDEs koennen diese Bloecke ausblenden, und um es einzukommentieren reicht dann das Aendern eines Zeichens.

M.E. ist das wichtigste an Kommentaren der Inhalt, nicht die Form. Aber zugegeben, eine gewisse Einheitlichkeit innerhalb eines Teams erleichtert das Lesen dann doch etwas.

[Stefan Zerbst]

das wichtigste an Kommentaren der Inhalt, nicht die Form

Spalter! Wie soll man sich gepflegt über Nichtigkeiten streiten wenn alles immer nur am Inhalt festgemacht wird? :mrgreen: