nicht angemeldet
Moin!
Hallo Liebe Community,
Kommentieren ist schon was feines und unabdingbar. Aber wie???
Es gibt bezogen auf "wertvolle", weil funktionale Kommentare, nur eine Möglichkeit:
/** kommentare */
Nur mit Doppelstern am Anfang wird dieser Kommentar in den PHP-Opcodes auftauchen und gecached, und steht via Reflection zur Verfügung.
Alle anderen Kommentartypen, die du erwähnt hast, verschwinden beim Parsen des Codes und stehen nur im Quelltext.
Die weitergehende Formatierung, also z.B.
/**
* @param $var string
* @param $object Foo
* @return \Bar\Baz
* @throws \InvalidArgumentException
*/
hängt ein wenig vom PHPDoc ab, was das auswertet. Daraus lesbare Dokumentation zu machen ist aus meiner persönlichen Erfahrung zwar nett, aber Spielkram. Wertvoll wird es erst durch die in diesem Code enthaltenen Typisierungen von Variablen (teilweise durch Typehints in den Parametern obsolet bzw. nur dort forcierbar) und vor allem Rückgabeparametern (nur in PHP 7 im Code angebbar, in PHP 5 ist man auf @return angewiesen).
Wenn du eine entsprechend mächtige IDE einsetzt (ich empfehle derzeit PHPStorm - kostet, ist das Geld aber wert), wird sie dir zum einen diese Kommentare nahezu automatisch generieren, wenn du möchtest, und sie zur Autovervollständigung von angefangenem Codetippen heranziehen.
Bezüglich des Unix-Perl-Kommentarzeichens # ist noch zu sagen, dass es im PEAR-Codingstandard als unerwünscht bezeichnet wird. Die Standards PSR-1/2 machen keine Aussagen zu Kommentaren, allerdings kann ich die PEAR-Herangehensweise durchaus verstehen: Einheitlichkeit ist Trumpf, und weil man mit den Hash-Zeichen keinen mehrzeiligen PHPDoc-Kommentar (mit Doppelstern) erzeugen kann, ist dieses Zeichen im Code eher ein Fremdkörperzeichen im Vergleich zu //.
P.S.: die 3 Methode finde ich reizvoller und eleganter da sie nur ein zeichen enthält das den kommentar einleitet. außerdem ist es von der "oberfläche" her größer als das Sternchen.
Da sie funktional eingeschränkt ist, kann sie niemand universell verwenden. Meine zeitweilige Nutzung des Hash-Kommentars war für Codezeilen, die ich temporär deaktivieren wollte. Das Zeichen fällt auf, wird regulär nicht in Code benutzt, und der PHP Code Sniffer hat eine Regel, um solche Kommentare zu finden und anzumeckern - falls also temporär deaktivierter Code aus Versehen eingecheckt wird, ist das eine gute automatische Methode, ihn zu entdecken.
Heutzutage: Zeilen markieren und in der IDE "Zeilen auskommentieren" tippen (Shift-Strg-Num7 oder so). Zeichen ist egal, Commits gehen mit "git add -p" und zeigen vor dem Staging noch mal alles an, was so geändert wurde (auch vergessene die() und var_dump(), nicht nur kommentierte Zeilen).
Grüße Sven
Auge