Kommentare

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.