Kommentare

Lesetipps

1. ExtJs – mächtig und kompliziert: Heute, der DataStore inkl. Models
2. PHP und callBacks
3. ValueObjects (Teil 2)

Kommentare sind das Tüpfelchen auf dem I eines guten Softwareprojektes. Leider findet man in den meisten Fällen ein Projekt nicht gut dokumentiert vor. Ich will hier aber zwischen Dokumentation und Kommentaren unterscheiden. Nach meiner Definition, die vielleicht nur für mich Gültigkeit besitzt, ist die Doku der Teil, der über den Methoden oder Klassen zu finden ist. PHPDoc wäre hier ein bekannter Vertreter. Kommentare hingegen findet man direkt im Code. Sie erklären, warum und was an dieser Code Stelle getan wird.

Hier soll es jetzt nur um die zweite Variante gehen. Da wir heute eine Diskussion über dieses Thema hatten und ich vor kurzen die Meinung von Martin Fowler zu diesem Thema gelesen habe will dieses Thema hier anschneiden. Laut Fowler und auch laut mir, sind Kommentare zwar eine super Idee, trotzdem versucht man dort zu hohe Komplexität zu kaschieren. Jeder Kommentar, der wirklich benötigt wird um das Verständnis zu erhalten, sollte untersucht werden. Durchschaut einfach mal euren Code und findet heraus, wann ihr Kommentare einsetzt. Oft gibt es auch denn Fall, dass man Kommentare verwendet, um Dinge zu gruppieren. Aber vielleicht einfach mal ein kleines Beispiel:

<?php
  ...
  public function store( )
  {
    // ...
    // store name
    $this->setVar( 'firstname', $firstname );
    $this->setVar( 'lastname', $lastname );

    $this->validateAddress( );
  }
  ...
?>

Dies ist jetzt natürlich ein sehr einfaches Beispiel, aber man kann schon sehen, dass man vielleicht die zwei Methoden, die sich mit dem Namen beschäftigen, zusammenfassen kann. Wenn ich schon Martin Fowler zitiere, dann ist die Lösung hier natürlich bereits klar: Refaktorisierung. Leider haben wir nicht das Glück in einem solchen Fall auf Unterstützung der IDE zurückzugreifen, deswegen machen wir es einfach von Hand. Ist bei dieser minimalen Komplexität natürlich auch machbar.

<?php
  ...
  public function store( )
  {
    // ...
    $this->storeName( $firstname, $lastname );

    $this->validateAddress( );
  }

  private function storeName( $firstname, $lastname )
  {
    $this->setVar( 'firstname', $firstname );
    $this->setVar( 'lastname', $lastname );
  }
  ...
?>

Fowler nennt diese Refaktorisierungsregel “Methode extrahieren“, was ja auch ganz passend ist. Vielleicht ist das Beispiel nicht unbedingt das passendste, ich denke aber es macht klar, was mit dieser Regel bewerkstelligt werden soll.

Bei unserer heutigen Diskussion waren wir uns nicht einig, in wie weit man jetzt diese Regel beherzigen sollte. Meiner Meinung nach ist es wirklich meistens der Fall, dass ein Kommentar versucht etwas zu vertuschen, dass man auch anders lösen kann.

Was man aber auf jeden Fall tun kann, ist sich seinen eigenen Code noch einmal unter diesem Aspekt anzusehen und für sich selbst zu entscheiden, was man tun sollte.

3 Kommentare »

• 
  

  Dubbel

  am 24. November 2008 um 18:09 Uhr

  Irgendwie klingt das plausibel, ist mir bisher noch nie so aufgefallen…naja ^^

  Ich benutze Kommentare auch oft als Platzhalter für weitere Ideen, die ich an dieser Stelle später eventuell noch umsetzten werde, oder als Markierung, wo eine Klasse aufhört und eine neue anfängt ( //### (…) ### – unschön aber effektiv

• 
  

  Ulf

  am 25. November 2008 um 12:25 Uhr

  Zwar ist der Beitrag von gestern aber egal…

  Ich finde das Beispiel etwas unpassend, da man bei konsequenter Anmeldeung dieser Regel schnell 100 oder mehr Funktionen hat. Ich sehe bei diesem Beispiel nicht die Notwendigkeit einer Extrahierung – auch schon nicht die Notwendigkeit eines Kommentars. Die Methoden-Signatur setVar ist doch wirklich aussagekräftig genug oder etwa nicht?

  Ansonsten gebe ich dir aber grundsätzlich Recht, überall da wo Kommentare benötigt werden, sind aussagenkräftigere Variablennamen bzw. Methodensignaturen meist sinnvoller.

  Viele Grüße aus Berlin
  Ulf

• 
  

  Clean Code – Überflüssige Kommentare | PHP hates me - Der PHP Blog

  am 21. Juni 2010 um 07:01 Uhr

  [...] Kommentare Im Informatikstudium erfährt man in einem Fach das man auf “Softwareentwicklung” verallgemeinern kann meistens wie wichtig es ist SÄMTLICHEN Quellcode zu dokumentieren. Als Grundgedanke ist das auch absolut erstrebenswert doch möchte ich hier nochmal die Frage aufwerfen wann zu viele bzw. falsche Kommentare mehr schaden als nutzen. [...]

RSS Feed für Kommentare zu diesem Artikel. TrackBack URL

Hinterlasse einen Kommentar