Effektives PHP -Kommentar

Der Schlüssel zum Schreiben von PHP -Kommentaren ist klar, nützlich und prägnant. 1. Kommentare sollten die Absicht hinter dem Code erläutern, anstatt nur den Code selbst zu beschreiben, z. B. den logischen Zweck komplexe bedingte Urteile zu erklären. 2. Fügen Sie Kommentare zu Schlüsselszenarien wie magische Werte, alte Codekompatibilität, API -Schnittstellen usw. hinzu, um die Lesbarkeit zu verbessern. 3. Vermeiden Sie doppelte Codeinhalte, halten Sie ihn präzise und spezifisch und verwenden Sie Standardformate wie PHPDOC. 4. Die Kommentare sollten synchron mit dem Code aktualisiert werden, um die Genauigkeit zu gewährleisten. Aus der Sicht anderer sollten gute Kommentare angesehen werden, die Kosten des Verständnisses senken und zu einem Codes verstehen, das Navigationsgerät versteht.

Das Schreiben von PHP -Kommentaren ist nicht schwierig, aber es ist eigentlich ganz Besonderes, sie klar, nützlich und ohne ausführlich zu schreiben. Viele Leute schreiben Kommentare entweder zu einfach, z. B. nur das Schreiben "Was macht diese Funktion?" Oder es ist zu kompliziert und sie können die wichtigsten Punkte nicht klar sehen. Ein wirklich effektiver PHP -Kommentar sollte dazu führen, dass die Menschen die Absicht auf einen Blick sehen und die Verständniskosten senken.

Warum müssen Sie die Kommentare klar schreiben?

Sie mögen denken, dass der Code von sich selbst sprechen kann, aber häufig variable Namen und Funktionsnamen drücken die Absicht hinter der Logik nicht vollständig aus. Vor allem, wenn die Geschäftslogik komplizierter ist, sind ohne Kommentare wie fehlende Straßenschilder, und andere (auch selbst) sind anfällig für sich, wenn sie zurückkehren, um den Code zu sehen.

Zum Beispiel:

 if ($ user-> Rolle! == 'admin' && $ user-> Status! == 'Active') {
    false zurückgeben;
}

Dieser Code sieht einfach aus, aber wenn Sie einen Kommentar hinzufügen:

 // Dieser Vorgang kann nicht von Nicht-Administratoren oder nicht aktivierten Benutzern durchgeführt werden

Dann ist die Bedeutung des gesamten Urteils viel klarer.

Daher besteht die Rolle der Annotation nicht nur darin, anzugeben, was getan wurde, sondern vor allem, um zu erklären, warum dies getan wird .

Wo ist die würdigste, kommentieren?

Nicht jede Codezeile benötigt Kommentare, aber die folgenden Szenarien werden empfohlen:

• Komplexes bedingtes Urteilsvermögen : dreifach oder mehr, wenn/sonst oder verschachtelte Logik.
• Wenn der magische Wert aus unbekannten Quellen stammt : Zum Beispiel $type = 3 , wenn 3 ein bestimmter Statuscode ist, ist es am besten, die Bedeutung anzugeben.
• Seltsam, aber muss alter Code erhalten bleiben : Manchmal müssen Sie einen uneleganten Code schreiben, um mit alten Systemen kompatibel zu sein, und die Kommentare können Ihnen helfen, "Ihre Haftung abzulehnen".
• API -Schnittstelle Parameter Beschreibung : Insbesondere die Rückgabewertstruktur ist für den Anrufer sehr kritisch.

Zum Beispiel:

 /**
 * Benutzerinformationen erhalten*
 * @param int $ userID Benutzer -ID
 * @Return Array enthält Namen, E -Mail, Rollenfelder*/
Funktion getUserInfo ($ userId) {
    // ...
}

Diese Art von Dokumentarfilmannotation kann auch in der IDE automatisch veranlasst werden und ist sehr praktisch.

Wie schreibe ich Kommentare, damit sie nicht "Unsinn" werden?

Es gibt auch Möglichkeiten, Kommentare zu schreiben, und Sie können sich auf die folgenden Punkte beziehen:

• Vermeiden Sie doppelte Codeinhalte : Schreiben Sie keine Kommentare wie "Title auf $ title", es sei denn, es gibt einen besonderen Grund.
• Halten Sie es einfach, aber spezifisch : Erklären Sie einfach den Zweck und Sie müssen keine lange Rede halten.
• Verwenden Sie Standardformate : Strukturierte Anmerkungen wie PHPDOC eignen sich besser für Teamarbeit.
• Kommentare rechtzeitig aktualisieren : Wenn der Code geändert wird, müssen die Kommentare gleichzeitig aktualisiert werden, sonst wird er schlechter als nicht.

Ein paar Tipps:

• Nachdem Sie einen Absatz der Logik geschrieben haben, schauen Sie zurück, um festzustellen, ob Sie Kommentare hinzufügen müssen.
• Achten Sie beim Betrachten des Code anderer Leute darauf, was Sie stecken macht, und das sind die Orte, die hinzugefügt werden sollten.
• Wenn Sie zweimal einen Code lesen, bevor Sie verstehen, sollten die Kommentare, die Sie jetzt schreiben, von anderen verstanden werden.

Grundsätzlich ist das

Der Kern wirksamer Anmerkungen besteht darin, aus der Perspektive anderer zu denken. Es ist kein Repeater für Code, sondern ein Navigator, um zu verstehen. Haben Sie keine Angst, Kommentare zu schreiben, sondern vermeiden Sie es, zufällig zu schreiben. Gutes Schreiben kann nicht nur anderen helfen, sondern Ihnen auch helfen, Ihre Ideen in Zukunft schnell zu finden.

Das obige ist der detaillierte Inhalt vonEffektives PHP -Kommentar. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!