Quelltext-Kommentar Styling-Tipps und Best Practices

Entwickler, die sich schon lange mit großen Projekten beschäftigt haben, wissen um die Bedeutung von Code-Kommentaren. Wenn Sie viele Funktionen in dieselbe Anwendung integrieren, werden die Dinge kompliziert. Es gibt so viele Datenbits, einschließlich Funktionen, Variablenreferenzen, Rückgabewerte, Parameter ... Wie sollen Sie mithalten??

Es ist keine Überraschung, dass das Kommentieren Ihres Codes sowohl für Einzel- als auch für Teamprojekte unerlässlich ist. Viele Entwickler wissen jedoch nicht, wie sie mit diesem Prozess umgehen sollen. Ich habe einige meiner persönlichen Tricks dargelegt Erstellen von sauberen, formatierten Code-Kommentaren. Standards und Kommentarvorlagen variieren zwischen den Entwicklern - aber letztendlich sollten Sie danach streben saubere und lesbare Kommentare um weitere verwirrende Bereiche in Ihrem Code näher zu erläutern.

Wir sollten anfangen, einige Unterschiede in der Kommentarformatierung zu diskutieren. Dadurch erhalten Sie eine bessere Vorstellung davon, wie detailliert Sie mit dem Projektcode werden können. Anschließend gebe ich einige konkrete Tipps und Beispiele, die Sie sofort anwenden können!

Kommentarstile: Eine Übersicht

Es sei darauf hingewiesen, dass diese vorgestellten Ideen nur sind Richtlinien auf sauberere Kommentare. Die einzelnen Programmiersprachen enthalten keine Richtlinien oder Angaben zum Einrichten Ihrer Dokumentation.

Allerdings haben sich moderne Entwickler zusammengetan, um ihr eigenes System zur Code-Kommentierung zu formatieren. Ich werde ein paar Mainstream-Stile anbieten und deren Zweck näher erläutern.

Inline-Kommentar

Praktisch jede Programmiersprache bietet Inline-Kommentare. Diese sind auf einzeilige Inhalte beschränkt und kommentieren den Text erst ab einem bestimmten Punkt. In C / C ++ beginnen Sie beispielsweise einen Inline-Kommentar wie folgt:

// begin variable Auflistung var myvar = 1;… 

Dies ist perfekt, um ein paar Sekunden lang in den Code einzugreifen möglicherweise verwirrende Funktionen erklären. Wenn Sie mit vielen Parametern oder Funktionsaufrufen arbeiten, können Sie eine Reihe von Inline-Kommentaren in der Nähe platzieren. Die vorteilhafteste Verwendung ist jedoch a einfache Erklärung für kleine Funktionen.

if (callAjax ($ params)) // callAjax erfolgreich mit Benutzerparametern ausführen… code

Beachten Sie vor allem, dass der Code nach der öffnenden Klammer in einer neuen Zeile stehen muss. Andernfalls würde alles in derselben Kommentarzeile stehen! Vermeiden Sie es, über Bord zu gehen Da Sie in der Regel keine einzeiligen Kommentare auf der gesamten Seite anzeigen müssen, ist dies vor allem bei verwirrenden Junctions im Code viel einfacher.

Beschreibende Blöcke

Wenn Sie eine ausführliche Erklärung hinzufügen müssen, ist ein einzelner Liner normalerweise nicht geeignet. In fast jedem Programmierbereich werden vorformatierte Kommentarvorlagen verwendet. Beschreibende Blöcke sind vor allem bei Funktionen und Bibliotheksdateien zu sehen. Wann immer Sie eine neue Funktion einrichten, ist es eine gute Praxis Fügen Sie über der Deklaration einen beschreibenden Block hinzu.

/ ** * @desc öffnet ein modales Fenster, um eine Nachricht anzuzeigen. * @param string $ msg - die anzuzeigende Nachricht * @return bool - Erfolg oder Fehler * / Funktion modalPopup ($ msg) … 

Oben ist ein einfaches Beispiel eines beschreibenden Funktionskommentars. Ich habe vermutlich eine Funktion in JavaScript geschrieben modalPopup was einen einzigen Parameter benötigt. In den obigen Kommentaren habe ich eine ähnliche Syntax wie phpDocumentor verwendet, bei der jeder Zeile ein a vorangestellt ist @ Symbol gefolgt von einem ausgewählten Schlüssel. Diese wirken sich in keiner Weise auf Ihren Code aus, Sie könnten also schreiben @Beschreibung anstatt @desc ohne irgendwelche Änderungen.

Diese kleinen Schlüssel werden tatsächlich aufgerufen Kommentar-Tags welche auf der Website ausführlich dokumentiert sind. Fühlen Sie sich frei, Ihre eigenen Ideen zusammenzustellen und verwenden Sie diese nach Belieben in Ihrem Code. Ich finde, sie helfen so, dass alles fließt Ich kann wichtige Informationen auf einen Blick prüfen. Sie sollten auch bemerken, dass ich die verwendet habe / * * / Kommentarformat im Blockstil. Das wird alles behalten viel sauberer als das Hinzufügen eines doppelten Schrägstrichs an jeder Zeile.

Gruppen- / Klassenkommentare

Neben dem Auskommentieren von Funktionen und Schleifen werden Blockbereiche nicht so häufig verwendet. Wo brauchst du wirklich stark Kommentare blockieren stehen an der Spitze Ihrer Backend-Dokumente oder Bibliotheksdateien. Es ist einfach, alles zu schreiben und eine solide Dokumentation für jede Datei auf Ihrer Website zu schreiben - wir können diese Vorgehensweise in vielen CMS wie WordPress sehen.

Der oberste Bereich Ihrer Seite sollte Kommentare zur Datei selbst enthalten. Auf diese Weise können Sie Überprüfen Sie schnell, wo Sie gerade arbeiten wenn Sie gleichzeitig auf mehreren Seiten arbeiten. Zusätzlich können Sie diesen Bereich als nutzen eine Datenbank mit den wichtigsten Funktionen, die Sie benötigen aus der Klasse.

/ ** * @desc Diese Klasse enthält Funktionen für Benutzerinteraktionen. Zu den Beispielen gehören user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstrakte Klasse myWebClass  

Sie sehen, ich habe nur eine kleine Probestunde für die Fälschung verwendet myWebClass Code. Ich habe einige Metainformationen hinzugefügt mit meinem Namen und E-Mail-Adresse für den Kontakt. Wenn Entwickler Open-Source-Code schreiben, ist dies im Allgemeinen eine gute Vorgehensweise. Daher wenden sich andere möglicherweise an Sie, um Unterstützung zu erhalten. Dies ist auch eine solide Methode, wenn Sie in größeren Entwicklungsteams arbeiten.

Das tag @erforderlich ist nicht etwas, was ich anderswo gesehen habe. In einigen meiner Projekte habe ich mit dem Format Schritt gehalten, nur auf Seiten, auf denen ich viele Methoden angepasst habe. Wann immer Sie Seiten in eine Datei einfügen, müssen diese vor der Ausgabe von Code erstellt werden. Das Hinzufügen dieser Details in den Hauptklassen-Kommentarblock ist daher eine gute Möglichkeit Erinnern Sie sich, welche Dateien benötigt werden.

Front-End-Code-Kommentar

Nachdem wir nun 3 wichtige Kommentarvorlagen behandelt haben, wollen wir uns ein paar andere Beispiele ansehen. Es gibt viele Frontend-Entwickler, die von statischem HTML in jQuery- und CSS-Code übergegangen sind. HTML-Kommentare sind im Vergleich zu Programmieranwendungen nicht so zweckmäßig, aber wenn Sie Stilbibliotheken und Seitenskripts erstellen, kann dies mit der Zeit unübersichtlich werden.

JavaScript folgt einer eher traditionellen Methode des Kommentierens, ähnlich wie Java, PHP und C / C++. CSS verwendet nur die Kommentare im Blockstil, die durch einen Schrägstrich und ein Sternchen gekennzeichnet sind. Sie sollten bedenken, dass Kommentare für Ihre Besucher offen angezeigt werden, da weder CSS noch JS serverseitig analysiert werden. Diese beiden Methoden eignen sich jedoch hervorragend, um informative Leckerbissen in Ihrem Code zu belassen, um sie zu wiederholen.

Insbesondere das Aufbrechen von CSS-Dateien kann eine lästige Aufgabe sein. Wir sind alle damit vertraut, einen Inline-Kommentar zu hinterlassen, um einen Fix für Internet Explorer oder Safari zu erklären. Ich glaube jedoch, dass CSS-Kommentare auf der Ebene von jQuery und PHP verwendet werden können. Lassen Sie uns näher auf die Erstellung von Stilgruppen eingehen, bevor Sie einige detaillierte Tipps zum Kommentieren von Code ansprechen.

CSS-Style-Gruppen

Für diejenigen, die seit Jahren CSS entwerfen, ist dies fast eine zweite Natur. Sie merken sich langsam alle Eigenschaften und die Syntax und bauen Ihr eigenes System für Stylesheets auf. Durch meine eigene Arbeit habe ich das geschaffen, was ich nenne Gruppierung um ähnliche CSS-Blöcke in einem Bereich zu paaren.

Wenn ich zurück zum CSS gehe, kann ich leicht finden, was ich in wenigen Sekunden brauche. Die Art und Weise, wie Sie Stile gruppieren, liegt ganz bei Ihnen, und das ist die Schönheit dieses Systems. Ich habe einige voreingestellte Standards, die ich unten umrissen habe:

• @resets - Standardränder, Füllzeichen, Schriftarten, Farben usw.
• @fonts - Absätze, Überschriften, Blockzitate, Links, Code
• @navigation - die wichtigsten Links zur Navigation auf der Website
• @layout - Wrapper, Container, Seitenleisten
• @header & @footer - diese können je nach Design variieren. Mögliche Stile sind Links und ungeordnete Listen, Fußzeilenspalten, Überschriften und Unternavigation

Beim Gruppieren von Stylesheets habe ich das gefunden Markierungssystem kann viel helfen. Im Gegensatz zu PHP oder JavaScript verwende ich jedoch eine einzige @Gruppe Tag gefolgt von einer Kategorie oder Schlüsselwörtern. Ich habe unten zwei Beispiele aufgeführt, damit Sie ein Gefühl dafür bekommen, was ich meine.

/ ** @group footer * / #footer styles…

/ ** @group Fußzeile, kleine Schriftarten, Spalten, externe Links ** / 

Sie können alternativ in jedem Kommentarblock ein wenig zusätzliche Details hinzufügen. Ich entscheide mich dafür Halten Sie die Dinge einfach und unkompliziert Die Stylesheets sind also leicht zu überfliegen. Beim Kommentieren dreht sich alles um die Dokumentation. Solange Sie die Schrift verstehen, ist es gut zu gehen!

4 Tipps zum besseren Kommentieren

In der ersten Hälfte dieses Artikels haben wir uns die verschiedenen Formate für die Codekommentierung angesehen. Lassen Sie uns nun einige allgemeine Tipps zum Reinigen, Organisieren und Verstehen Ihres Codes diskutieren.

1. Alles lesbar halten

Manchmal vergessen wir als Entwickler das Wir schreiben Kommentare, die der Mensch lesen soll. Alle Programmiersprachen, die wir verstehen, sind für Maschinen gedacht, daher kann es mühsam sein, sie in einfachen Text umzuwandeln. Es ist wichtig zu wissen, dass wir nicht hier sind, um eine Forschungsarbeit auf College-Ebene zu schreiben, aber Nur noch ein paar Tipps!

function getTheMail () // code hier wird E-Mail / * run-Code erstellen, wenn unser benutzerdefinierter Funktionsaufruf sendMyMail () true zurückgibt. find sendMyMail () in /libs/mailer.class.php und Nachricht wird gesendet! * / if (sendMyMail ()) return true; // Bleibe wahr und zeige den Erfolg auf dem Bildschirm an

Auch nur ein paar Worte sind besser als nichts. Wenn Sie in Zukunft Projekte bearbeiten und bearbeiten, überrascht es oft, wie viel Sie vergessen werden. Da Sie nicht jeden Tag die gleichen Variablen und Funktionsnamen betrachten, vergessen Sie die Mehrheit Ihres Codes langsam. So kannst du Hinterlasse niemals zu viele Kommentare! Sie können jedoch zu viele schlechte Kommentare hinterlassen.

Als Faustregel gilt, Nehmen Sie sich etwas Zeit, bevor Sie schreiben. Frag dich selbst Was ist am verwirrendsten über das Programm und wie kannst du es am besten erklären in “Dummy” Sprache? Bedenken Sie auch Warum schreibst du den Code genau so, wie du bist.

Einige der verwirrendsten Fehler werden angezeigt, wenn Sie den Zweck von benutzerdefinierten Funktionen (oder Funktionen von Drittanbietern) vergessen. Hinterlassen Sie einen Kommentarpfad, der zu einigen anderen Dateien führt Wenn Sie sich so leichter an die Funktionalität erinnern können.

2. Erleichtern Sie etwas Platz!

Ich kann gar nicht genug betonen, wie wichtig es ist Leerraum kann sein. Das geht doppelt wahr für PHP- und Ruby-Entwickler, die an riesigen Websites mit Hunderten von Dateien arbeiten. Sie werden diesen Code den ganzen Tag lang anstarren! Wäre es nicht toll, wenn Sie einfach zu den wichtigen Bereichen gehen würden??

$ dir1 = "/ home /"; // Set home home directory $ myCurrentDir = getCurDirr (); // das aktuelle Benutzerverzeichnis setzen $ userVar = $ get_username (); // Benutzername des aktuellen Benutzers

Im obigen Beispiel werden Sie feststellen, dass in jeder Zeile ein zusätzlicher Abstand zwischen den Kommentaren und dem Code eingefügt wurde. Während Sie durch die Dateien blättern, wird diese Art des Kommentierens verwendet deutlich hervorheben. Es macht das Finden von Fehlern und die Korrektur Ihres Codes um Hunderte Male einfacher wenn variable Blöcke so sind sauber.

Sie könnten eine ähnliche Aufgabe mit dem Code in einer Funktion ausführen, bei der Sie verwirrt sind, wie sie funktioniert, aber diese Methode würde Ihren Code mit Inline-Kommentaren überladen, und genau das Gegenteil von ordentlich! Ich empfehle in diesem Szenario Hinzufügen eines großen Blockzeilen-Kommentars um den Logikbereich.

$ (document) .ready (function () $ ('. sub'). hide (); // Unterraumnavigation auf Seite / Seite ausblenden / **) Überprüfen Sie, ob auf einem Anker in .itm div ein Klickereignis vorhanden ist Aktion, damit sich die Seite beim Klicken nicht ändert. Greifen Sie auf das übergeordnete Element von .itm zu, gefolgt von der nächsten .sub-Liste, um zwischen Öffnen / Schließen umzuschalten ** / $ ('. itm a'). live ('click', Funktion (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Dies ist ein kleiner Teil von jQuery-Code, der auf ein Untermenü ausgerichtet ist, das die Navigation durchläuft. Der erste Kommentar ist inline, um zu erklären, warum wir alles verstecken .Sub Klassen. Über dem Live-Click-Eventhandler habe ich einen Blockkommentar und verwendet alle Schriften auf denselben Punkt eingerückt. Das macht die Sache hübscher und nicht nur nachlässig - vor allem für andere, die Ihre Kommentare lesen.

3. Kommentar während der Codierung

Zusammen mit dem richtigen Abstand kann dies eine der besten Gewohnheiten sein, in die man einsteigen kann. Niemand möchte sein Programm nach der Arbeit noch einmal durchgehen und jedes Stück dokumentieren. Die meisten von uns möchten nicht einmal zurückgehen und die verwirrenden Bereiche dokumentieren! Es kostet wirklich viel Arbeit.

Aber wenn Sie die Kommentare schreiben können, während Sie programmieren Alles wird noch frisch in deinem Kopf sein. Normalerweise bleiben Entwickler bei einem Problem stecken und durchsuchen das Web nach der einfachsten Lösung. Wenn Sie den Eureka-Moment treffen und ein solches Problem lösen, besteht im Allgemeinen ein Moment der Klarheit, in dem Sie Ihre vorherigen Fehler verstehen. Das wäre das beste Zeit um offene und ehrliche Kommentare zu Ihrem Code zu hinterlassen.

Darüber hinaus können Sie sich daran gewöhnen, alle Ihre Dateien zu kommentieren. Die Zeit, die erforderlich ist, um zurückzugehen und herauszufinden, wie etwas funktioniert, ist viel größer, nachdem Sie die Funktion bereits erstellt haben. Sowohl Ihr zukünftiges Ich als auch Ihre Teamkollegen werden es Ihnen danken, dass Sie Ihre Kommentare im Voraus abgegeben haben.

4. Umgang mit fehlerhaften Fehlern

Wir können nicht alle stundenlang vor dem Computer sitzen und Code schreiben. Ich denke, wir können es versuchen, aber irgendwann müssen wir schlafen! Sie müssen sich wahrscheinlich mit dem Code für den Tag trennen, wobei einige Funktionen immer noch fehlerhaft sind. In diesem Szenario ist es wichtig, dass Sie Lassen Sie lange, ausführliche Kommentare darüber, wo Sie die Dinge verlassen haben.

Selbst nach einer erholsamen Nachtruhe sind Sie vielleicht überrascht, wie schwierig es sein kann, wieder in den Kodierungsschwung zu geraten. Wenn Sie beispielsweise eine Seite zum Hochladen von Bildern erstellen und diese unvollständig lassen müssen, müssen Sie Sie sollten angeben, wo Sie aufgehört haben. Werden die Bilder hochgeladen und im temporären Speicher gespeichert? Oder sie werden möglicherweise nicht einmal im Upload-Formular erkannt oder nach dem Upload auf der Seite nicht richtig angezeigt.

Fehler zu kommentieren ist aus zwei Hauptgründen wichtig. Zuerst kannst du leicht aufheben, wo Sie aufgehört haben und Versuchen Sie es erneut, um das Problem bzw. die Probleme zu beheben.. Und zweitens kannst du unterscheiden Sie zwischen der Live-Version Ihrer Website und den Testgeländen. Denken Sie daran, dass Kommentare verwendet werden sollten Erklären Sie, warum Sie etwas tun, nicht genau das, was es tut.

Fazit

Die Entwicklung von Web-Apps und -Software ist eine erfüllende, wenn auch schwierige Praxis. Wenn Sie zu den wenigen Entwicklern gehören, die das Erstellen von Software wirklich verstehen, ist es wichtig, dass Sie sich mit Ihren Programmierkenntnissen auskennen. Das Beschreiben von beschreibenden Kommentaren ist auf lange Sicht nur eine gute Praxis, und du wirst es wahrscheinlich nie bereuen!

Wenn Sie Vorschläge für eine klarere Codekommentierung haben, teilen Sie uns dies im Diskussionsbereich mit!