PHP Code kommentieren – aber richtig!

0
134

@PHP Code Dokumentation – wie kommentiere ich meinen Code korrekt?

Im Laufe meines Programmierlebens habe ich einige Arten von Code Comments kennen gelernt. Hier einige Beispiele:


<?php 

// Some Methode, tbd 

/* Class, gibt false zurück */ 

/** 
  * Class Foo 
  * Holt Daten aus der DB, bereit auf und gibt diese zurück 
  * 
  * @Todo: Kommentar überarbeiten 
  */ 

?>

Für mich als Entwickler sind diese Dokumentationen erstmal nicht sinnvoll – sondern eher unnötiger Ballast in einem Quelltext.

Es geht aber besser – Grundlegendes!

Kommentare können zeilenbasiert sein, in diesem Fall verwenden wir folgendes:

<?php 

$x = 40; // Zähler 

function rechne($a, $b) 
{ 
    // ... no implementation 
} 

?>

Dies sind Hilfskommentare, die beispielsweise von Code Dokumentationstools wie PHPDoc nicht gelesen werden.

Und Kommentarblöcke, diese haben definierte Annotations:

<?php 

/** 
  * Variable für das Brutto Entgelt 
  * 
  * @var int 
  */ 
public $brutto; 

?>

Die wichtigsten Tags für Kommentarblöcke

Hier mal eine kurze Liste der wichtigsten Tags für Kommentarblöcke, gefolgt mit einem Beispiel

  • @access – @access public
  • @author – @author Matthias Rudolf <info@noobis.de>
  • @param – @param bool|mixed|string|int $foo Und dies ist die Beschreibung zur Variable
  • @return – @return bool|mixed|string|int Und eine Beschreibung was zurück gegeben wird
  • @see – @see class::method::function::var (Möglichkeit, auf eine andere Klasse, Methode etc. zu verweisen)
  • @todo – @todo Mit Information zum ToDo
  • @var – @var string Und die Beschreibung zur Variabel die man dokumentieren möchte (Verwendung bei Variabeln die kommentiert werden sollen)
  • @version – @version 1.0: Funktion neu erstellt
  • @package – @package modul_package (Darf nur aus einem Wort und folgende Zeichen bestehen: „_“, „-„, „[„, „]“)

Weitergehende Informationen werden direkt bei dem PHP Documentor zur Verfügung gestellt: http://manual.phpdoc.org/HTMLframesConverter/default/

Bei einer guten Dokumentation – was ist zu beachten?

  1. Verwenden sie immer eindeutige Kommentare!
  2. Halten sie diese kurz – und auf das wesentliche beschränkt!
  3. Beachten sie den Grundsatz: Guter Quelltext ist auch ohne Kommentar lesbar!

Kommentiert ihr euren Code immer? Habt ihr Vorschläge oder Verbesserungen zum Artikel?
Lasst es uns doch über die Kommentarfunktion wissen. Vielen Dank hierfür vorab!

HINTERLASSEN SIE EINE ANTWORT

Please enter your comment!
Please enter your name here