In den letzten zwei Monaten, in denen ich PHP gelernt habe, habe ich mehr als zwei Stile identifiziert, die Leute verwenden, um Code zu kommentieren! Ich habe nicht viel Konsistenz gesehen ... was meiner Meinung nach normalerweise Künstler bei der Arbeit bedeutet. Also habe ich mich gefragt: Was sind die gültigen Arten zu kommentieren, die noch lesbar / praktisch sind? Wenn Sie alle gültigen Möglichkeiten an einem Ort nebeneinander sehen, erhalten Sie den Überblick, den ich suche, um die Kommentare zu verbessern.
%Vor%Zitieren des Handbuchs für Kommentare:
%Vor%PHP unterstützt C-, C ++ - und Unix-Shell-Stil-Kommentare (Perl-Stil). Zum Beispiel:
Im Allgemeinen sollten Sie Kommentare in Ihrem Quellcode vermeiden . Um Martin Fowler zu zitieren:
Wenn Sie das Gefühl haben, einen Kommentar schreiben zu müssen, versuchen Sie zunächst, den Code zu überarbeiten, so dass Kommentare überflüssig werden.
was soviel wie
bedeutet %Vor%sollte in
umgeschrieben werden %Vor%Ein weiterer Kommentartyp, auf den Sie manchmal treffen werden, ist der Trennzeichenkommentar, z. etwas wie
%Vor%oder
%Vor%Dies deutet normalerweise darauf hin, dass der Code, in dem sie verwendet werden, zu viel macht. Wenn Sie dies in einer Klasse finden, überprüfen Sie die Verantwortlichkeit der Klasse und prüfen Sie, ob einige Teile besser in eine eigenständige Klasse umgewandelt werden können.
Wie bei API-Dokumenten lautet die allgemeine Schreibweise PHPDoc , z. B.
%Vor%Ich würde argumentieren, dass Sie Short und Long Desc weglassen können, wenn die verbleibende Methodensignatur klar kommuniziert, was sie tut. Dies erfordert jedoch eine gewisse Disziplin und Wissen darüber, wie man Clean Code schreibt. Zum Beispiel ist das Folgende völlig überflüssig:
%Vor%und sollte auf
verkürzt werden %Vor%Unnötig zu sagen, ob Sie sich für die vollständige API-Dokumentation entscheiden oder nicht, hängt auch vom Projekt ab. Ich würde jedes Framework erwarten, das ich herunterladen und verwenden kann, um vollständige API-Dokumente zu haben. Wichtig ist nur, dass, was auch immer Sie sich entscheiden, tun Sie es konsequent.
Sie sollten unbedingt die phpdoc-Standards verwenden. Hier ist ein Schnellstart für Anfänger.
Ich bin sicher, Sie haben Kommentare wie folgt gesehen:
%Vor%Das Kommentieren ist für die meisten PHP-Entwickler nicht nur einfach zu lesen, sondern Sie können auch schöne Dokumentationen erzeugen.
Für mich sieht jeder von ihnen gleich gut aus.
Ich verwende sowohl Einzeiler als auch mehrzeilige Kommentare.
Da sie grau hervorgehoben sind, sind sie immer sichtbar und unterscheiden sich von anderem Code.
Ich habe kein Problem mit der Lesbarkeit von Kommentaren vor
Es ist ziemlich üblich, phpdoc Richtlinien zum Kommentieren zu verwenden. Dazu gehören Anmerkungen zum Erstellen einer Dokumentation.
Tags und Links php coding-style comments commenting