Kommentieren in PHP

[.MB]

Hallo Liebe Community,

Kommentieren ist schon was feines und unabdingbar. Aber wie???

Ich hab mir einige Tipps von euch geben lassen. die fruchten bezogen auf Inhalt und markant stellen im Code. @param is sehr sinnvoll und andere schlüsselbegriffe auch. Die Art eineder Kommentare einer "Java-Konvention" macht mich stutzig.

Entschieden länger

/*
 * Bla bla:
 * @param bla_bla
 */

Mit einem kommentarzeichen mehr

// Bla bla:
// @param bla_bla

sehr kurz und kompakt

# Bla bla:
# @param bla_bla

was will man mit dieser raumgebenden ersten Kommentar-Methode erreichen? für mich sehr verwirrent

LG MB

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.

[Auge]

Hallo

@param is sehr sinnvoll und andere schlüsselbegriffe auch. Die Art eineder Kommentare einer "Java-Konvention" macht mich stutzig.

Wenn du schon weißt, dass es sich bei dieser Art zu kommentieren um eine „Java-Konvention“ handelt, hättest du auch mal gleich danach suchen können und wärst erst auf JavaDoc und dann auch gleich auf phpDocumentor gestoßen.

was will man mit dieser raumgebenden ersten Kommentar-Methode erreichen? für mich sehr verwirrent

Erreichen will man, dass ein typischerweise in IDEs eignebauter Parser anspringt und aus den Kommentaren Code-Dokumentation macht. Die ist dann im ganzen Projekt verfügbar und zeigt bei der Eingabe z.B. von Funktionsnamen die definierten Parameter und Rückgabewerte.

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.

Kannst du machen, wie du willst oder es das Projekt, an dem du beteiligt bist, regelt.

Tschö, Auge

[dedlfix]

Tach!

was will man mit dieser raumgebenden ersten Kommentar-Methode erreichen? für mich sehr verwirrent

Erreichen will man, dass ein typischerweise in IDEs eignebauter Parser anspringt und aus den Kommentaren Code-Dokumentation macht. Die ist dann im ganzen Projekt verfügbar und zeigt bei der Eingabe z.B. von Funktionsnamen die definierten Parameter und Rückgabewerte.

Dazu muss der Kommentarblock aber mit zwei Sternchen beginnen (also /**), sonst ignoriert der PhpDoc-Interpreter diesen Kommentarblock. Damit kann man unterscheiden zwischen dokumentationsfähigen Kommentaren und welchen, die einfach nur so im Code stehen.

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.

Dann braucht man aber kein @param und ähnliches, weil es eh nicht interpretiert wird.

dedlfix.

[Auge]

Hallo

Erreichen will man, dass ein typischerweise in IDEs eignebauter Parser anspringt und aus den Kommentaren Code-Dokumentation macht. Die ist dann im ganzen Projekt verfügbar und zeigt bei der Eingabe z.B. von Funktionsnamen die definierten Parameter und Rückgabewerte.

Dazu muss der Kommentarblock aber mit zwei Sternchen beginnen (also /**), sonst ignoriert der PhpDoc-Interpreter diesen Kommentarblock.

Mist! Ich wusste, dass noch etwas fehlt. Beim Schreiben habe ich noch dran gedacht. Danach zweimal editiert und immer noch nicht ganz richtig. Immer is irgendwas. *grml*

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.

Dann braucht man aber kein @param und ähnliches, weil es eh nicht interpretiert wird.

Es spricht aber auch nichts dagegen, falls mandiese Notation selbst für hilfreich hält. Sie erfüllt halt nur nicht den Zweck, zu dem sie entwickelt wurde.

Tschö, Auge

[1unitedpower]

Erreichen will man, dass ein typischerweise in IDEs eignebauter Parser anspringt und aus den Kommentaren Code-Dokumentation macht. Die ist dann im ganzen Projekt verfügbar und zeigt bei der Eingabe z.B. von Funktionsnamen die definierten Parameter und Rückgabewerte.

Inzwischen haben phpdoc-Kommentare häufig sogar eine eigene Semantik, die über die bloße Dokumentation weit hinausgeht. Beispiele dafür sind Typchecker, Object-relational-Mapper und Service-Locator-Pattern, die sich als Dependency-Injection missverstehen. Der Missbrauch der Kommentare wurde aus der Not heraus geboren, weil PHP kaum Mittel für Metaprogrammierung bietet.

[Jörg Reinholz]

Moin!

Ein paar Denkanstöße:

• Kommentare kann man zu einer Dokumentation umwandeln.
• Die unterschiedlichen Arten haben teils tradierte Vorläufer in C und Perl
• Dann gibt es noch einzeilige Kommentare (#,//) und mehrzeilige (/* … */)
• Dann wäre da noch eine Methode zu Abschalten bzw. Anschalten ganzer Blöcke mit nur einem Zeichen.

Probiere mal:

<?php
function gruesse ($s) {
   return "Hallo $s";
}

# Test:
#/* 
echo gruesse('Karl'), "\n";
echo gruesse('Monika'), "\n";
#*/

und:

<?php
function gruesse ($s) {
   return "Hallo $s";
}

# Test:
/* 
echo gruesse('Karl'), "\n";
echo gruesse('Monika'), "\n";
#*/

Jörg Reinholz

[.MB]

Ok habe ich gehört und ich sehe paralelen. Besten Dank für AW.

LGMB

[Sven Rautenberg]

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