Startup-Code: Kommentare im Quelltext

Es ist immer wieder ein gerne diskutiertes Thema „Kommentare im Quelltext“ – allen voran die sogenannten Inline-Kommentare.

Das Kommentare sinnvoll und in jedem guten Softwareprojekt elementarer Bestandteil sind, dessen ist sich die Mehrheit der Entwickler und Projektverantwortlichen mittlerweile tendenziell sicher. Doch es gibt sie noch, die andere Seite – Software ohne Kommentare und das bei Projekten die mitunter aus tausenden Zeilen Code und einer Vielzahl von Dateien besteht und so groß gewachsen sind, dass man sich in Eigenregie nur schwer einen Reim aus dem machen kann, was man da teilweise vor sich hat.

Es ist zum einen wirtschaftlich betrachtet, geradezu fatal solche Projekte nicht umgehend einer großen Review zu unterziehen und entsprechende Gegenmaßnahmen einzuleiten (z.B. basierend auf dem Pfadfinderprinzip) um die Erosion einzugrenzen. Einer meiner Wegbegleiter sagte mal zu mir: „Zu jeder Zeile Code, schreibt man eine Zeile Kommentar“ (statistisch betrachtet). Mal benötigt man etwas mehr Dokumentation und ein anderes Mal etwas weniger.

Ja richtig, Entwickler könnten auch einfach den Code lesen, den diese auch sicherlich verstehen würden, doch dauert dies sehr viel länger und kostet entsprechend auch mehr – Zeit ist Geld – auch hier – ganz einfach. Wenn allerdings gar nicht oder zu wenig kommentiert wurde, dann wage ich auch zu bezweifeln, dass andere wichtige Grundlagen einer sauberen Code-Basis eingehalten wurden, wie z.B. „…das Bezeichner im Code sprechend formuliert wurden, der Code für sich alleine stehen kann und so aussieht als wäre er von jemanden geschrieben worden, dem dies wirklich wichtig war…“. Da ist sie auch schon die Überleitung zu Uncle Bob. Während ich diese Aussage von ihm durchaus als richtig erachte, halte ich seine Einstellung oder Vorstellung zu/von Kommentaren einfach für nicht richtig. Seine Meinung dazu geht in die Richtung „Guter Code ist so lesbar und bedarf keiner Kommentare“ (Kurzübersetzung aus Clean Code). So eine Aussage kenne sonst nur als Ausrede für ein unzureichendes Arbeitsergebnis.

Mit Kommentaren addressiert man auf einer ganz anderen Ebene. Es geht um ein optisch erfassbares vom Code gelöstes Element und das ist eben der Kommentar, der auch dann noch verständlich ist, wenn die darunterliegenden Zeilen Code nicht mehr verstanden werden. Achtung! Auch Kommentare sind kein Heilmittel für schlechten Code. Wenn der Code zu komplex wurde oder man bemerkt, dass eine Methode aufgebläht ist (Stichwort SRP) und NUR NOCH durch die geschriebenen Kommentare erklärt werden kann, dann ist dies ein klares Zeichen für einen Smell und ein ggf. benötigtes Refactoring.

Besonders häufig habe ich die zuvor beschriebene Art Code übrigens vorgefunden, wenn z. B. Unternehmer/Gründer/Entrepreneure (die auch auf die Time-to-Market achten und die auch müssen/sollten), diesen im Auftrag produzieren lassen und von Qualitätsmanagement im Software-Umfeld einfach nichts verstehen, selber keinen technischen Background haben oder eine Mischung aus beiden und ggf. noch weiteren Faktoren. Jedenfalls kann man davon ausgehen, auf solchen Code zu stoßen, wenn es sich um „im Auftrag entwickelte Software“ oder um „Startup-Software“ handelte. Ich finde den Begriff Startup-Code so passend, dass ich diesen auch beibehalten werde. Ich schreibe gerade noch an einem Kapitel in meinem aktuellen Buchprojekt, für das ich nach einem passenden Begriff für deartigen crappy– oder legacy-code gesucht habe der einfach passender ist als das was bisher so gehört hat. Wie sind eure Erfahrungen? Kennt ihr weitere Namen für deartigen Code?

Summary
Article Name
Startup-Code: Kommentare im Quelltext
Description
Dieser Artikel deutet die Wichtigkeit und die Wertigkeit von Kommentaren im Quelltext an. Hinterfragt die Notwendigkeit und zeigt mögliche Probleme auf. Startup-Code wie ich diese Art Code getauft habe, habe ich in meiner Laufbahn zu oft gesehen und oft wurde ich gefragt ob und wie man derartige Software retten könnte. Ein Versuch aufzuzeigen, weshalb Kommentar so wichtig sind ...
Author
Publisher Name
phpfluesterer.de
Publisher Logo

2 Antworten zu “Startup-Code: Kommentare im Quelltext”

  1. Jan sagt:

    /**
    * get the price
    */
    public function getPrice()
    {
    return $this->_price;
    }

    Solche und ähnliche Kommentare sehe ich häufig; sie sind einfach nicht hilfreich sondern nur der Vollständigkeit halber vorhanden. Genauso nutzlos sind Kommentare zu Funktion, die mit „This is a function for …“ oder ähnlichem beginnen. Auch solche Phrasen kann man sich sparen, denn jeder sieht ja, dass der Kommentar zu einer Funktion gehört. Kommentieren ist nur dann gut, wenn die Kommentare die Lesbarkeit des Quelltextes verbessern. Guter Code benötigt meiner Meinung nach wenig Kommentare. Er liest sich wie ein Artikel in einer Fachzeitschrift, die Kommentare sind dabei wie Fußnoten.

  2. Hallo Jan,

    du hast selbstverständlich recht mit deinen Schlußworten:
    „Guter Code benötigt meiner Meinung nach wenig Kommentare. Er liest sich wie ein Artikel in einer Fachzeitschrift, die Kommentare sind dabei wie Fußnoten.“

    Doch das muss nicht unbedingt ein Widerspruch zu dem was ich geschrieben habe sein. Bezüglich der von dir erwähnten Phrasen:
    Sicherlich kommt es einem wie eine Phrase vor, wenn man an jeder Methode eine solche Einleitung sieht. Dennoch ist es wünschenswert, eine Formulierung in einer gewissen Form einzuleiten, ggf. variiert man hier ein wenig. Doch man sollte nicht darauf verzichten eine schöne Formulierung zu verwenden. Befreit man sich aus dem aktuellen Fokus und stellt sich eine generierte Dokumentation vor, in der der Code nicht auf den ersten Blick mit eingebettet ist, dann macht eine „Phrase“ schon wieder Sinn und die Dokumentation besser lesbar. Dann ist eine Einleitung wie z. B. „This method is intend to …“ wieder ein schönes Stilmittel.

    Aber trotzdem ist es wichtig zwischen Standardmethoden wie __construct und sämtliche anderen Magics, sowie getter, setter und ggf. weiteren zu unterscheiden.

    Ich habe in meinem Team immer die Regelung eingeführt, dass man jede Methode dokumentiert und zwar nach einem Standard-Template. Der Rahmen und die Verwendung sind also vorgegeben und der Entwickler muss lediglich einen sinnvollen Inhalt beisteuern. Durch diese Regelung nimmt man dem Entwickler bei jeder neu geschriebenen Methode eine Überlegung ab und ersetzt diese durch einen Automatismus – dem Schreiben eines Kommentares – und zwar in jedem Fall. Denn überlasse ich in einem großen Team jedem einzelnen Entwickler die Entscheidung wann ein Kommentar geschrieben wird, ist das Ergebnis nicht mehr vorhersehbar. Diesen Umstand umgehe ich mit einer einfachen Regel. Die Schwankungen sowie das Verantwortungsgefühl sind in Teams meinen Erfahrungen nach, stets unterschiedlich ausgeprägt.

    Beim Inhalt ist dann der Entwickler gefragt und kann sich, statt sich Gedanken zu machen, ob und wie er einen Kommentar schreibt, darauf konzentrieren einen sinnvollen Kommentar zu schreiben und somit einen Mehrwert zu schaffen.

    Wir haben im Team eine Regelung die z. B. für getter und setter einen Kommentar vorsieht, der in etwa wie folgt aussieht:

    /**
    * Getter for _xyz
    *
    * @…
    * …
    */

    bzw.

    /**
    * Setter for _xyz
    *
    * @…
    * …
    */

    Simpel, überschaubar und doch dokumentiert. In diesem Beispiel muss keine Einleitung geschrieben werden, da getter und setter bekannt sind. Der Zweck ist klar vorgegeben und somit entfällt hier die Notwendigkeit ausschweifend zu dokumentieren.

    Habe ich aber z. B. einen elementaren Teil der Business-Logik vor mir und ich bin gefragt einen sinnvollen Kommentar zu schreiben, dann nehme ich mir die Zeit und beschreibe/dokumentiere im Detail was hier geschieht, warum es geschieht, ggf. warum eine besondere Form der Implementierung gewählt wurde und wenn möglich vielleicht sogar noch ein @link mit einem Verweis in das Unternehmenswiki o. ä. – oder mit einem @see zu einem Punkt für weiterführende Informationen.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.

*