Quellcode Kommentar Styling: Tipps und Best Practices

Entwickler, die ihre Zeit in großen Projekten verbracht haben, verstehen die Bedeutung von Code-Kommentaren. Wenn Sie viele Funktionen in derselben Anwendung erstellen, werden die Dinge oft kompliziert. Es gibt so viele Datenbits, einschließlich Funktionen, Variablenreferenzen, Rückgabewerte, Parameter ... wie wird von Ihnen erwartet, dass Sie mithalten?

Es ist daher nicht verwunderlich, dass das Kommentieren von Code sowohl für Einzel- als auch für Teamprojekte unerlässlich ist. Viele Entwickler wissen jedoch nicht, wie sie diesen Prozess durchführen sollen. Ich habe einige meiner persönlichen Tricks zum Erstellen von sauberen, formatierten Code-Kommentaren skizziert. Standards und Kommentarvorlagen variieren zwischen den Entwicklern - aber letztendlich sollten Sie nach sauberen und lesbaren Kommentaren streben, um verwirrende Bereiche in Ihrem Code zu erklären.

Wir sollten anfangen, einige der Unterschiede in der Formatierung von Kommentaren zu diskutieren. Dadurch erhalten Sie eine bessere Vorstellung davon, wie detailliert Sie mit Projektcode werden können. Danach biete ich Ihnen einige konkrete Tipps und Beispiele an, die Sie sofort einsetzen können!

Kommentarvorlagen: Ein Überblick

Es sollte angemerkt werden, dass diese vorgestellten Ideen lediglich Richtlinien für sauberere Kommentare sind. Die einzelnen Programmiersprachen enthalten keine Richtlinien oder Spezifikationen für die Einrichtung Ihrer Dokumentation.

Davon abgesehen haben sich moderne Entwickler zusammengefunden, um ihr eigenes System der Code-Kommentierung zu formatieren. Ich werde ein paar Mainstream-Stile anbieten und detailliert auf ihren Zweck eingehen.

Inline kommentieren

Praktisch jede einzelne Programmiersprache bietet Inline-Kommentare . Diese sind auf einzeiligen Inhalt beschränkt und kommentieren den Text erst nach einem bestimmten Punkt. Zum Beispiel in C / C ++ beginnen Sie einen Inline-Kommentar wie folgt:

 // Beginn der Variablenliste var myvar = 1; .. 

Dies ist perfekt, wenn Sie einige Sekunden lang in den Code eintauchen, um möglicherweise verwirrende Funktionen zu erklären . Wenn Sie mit vielen Parametern oder Funktionsaufrufen arbeiten, können Sie eine Reihe von Inline-Kommentaren in der Nähe platzieren. Aber die nützlichste Verwendung ist eine einfältige Erklärung für kleine Funktionalität .

 if (callAjax ($ params)) {// erfolgreich callAjax mit Benutzerparametern ausführen ... code} 

Beachten Sie vor allem, dass der Code nach der öffnenden Klammer in einer neuen Zeile stehen muss. Sonst würde alles auf derselben Kommentarzeile abgefangen! Vermeiden Sie es, über Bord zu gehen, da Sie in der Regel keine Einzeilerkommentare auf der ganzen Seite sehen müssen, aber besonders für verwirrende Junctions in Ihrem Code sind diese viel einfacher in der letzten Minute einzufügen.

Beschreibende Blöcke

Wenn Sie eine große Erklärung benötigen, ist ein einzelner Liner nicht geeignet. Es gibt vorformatierte Kommentarvorlagen, die in jedem Bereich der Programmierung verwendet werden. Beschreibende Blöcke werden vor allem um Funktionen und Bibliotheksdateien herum gesehen. Wenn Sie eine neue Funktion einrichten, empfiehlt es sich , oberhalb der Deklaration einen beschreibenden Block hinzuzufügen .

 / ** * @desc öffnet ein modales Fenster zum Anzeigen einer Nachricht * @param string $ msg - die anzuzeigende Nachricht * @return bool - Erfolg oder Misserfolg * / function modalPopup ($ msg) {...} 

Oben ist ein einfaches Beispiel für einen beschreibenden Funktionskommentar. Ich habe eine Funktion vermutlich in JavaScript geschrieben, die ModalPopup genannt wird, das einen einzelnen Parameter nimmt. In den obigen Kommentaren habe ich eine ähnliche Syntax wie phpDocumentor verwendet, wobei jeder Zeile ein @ -Zeichen gefolgt von einem ausgewählten Schlüssel vorangestellt ist. Diese werden Ihren Code in keiner Weise beeinflussen, so dass Sie @description anstelle von @desc ohne irgendwelche Änderungen schreiben @description .

Diese kleinen Schlüssel heißen eigentlich Kommentar-Tags, die auf der Website stark dokumentiert sind. Fühlen Sie sich frei, Ihre eigenen zu erstellen und verwenden Sie, wie Sie in Ihrem Code wünschen. Ich finde, dass sie helfen, alles im Fluss zu halten, damit ich wichtige Informationen auf einen Blick überprüfen kann . Sie sollten auch bemerken, dass ich das Kommentarformat " /* */ Block" verwendet habe. Dies wird alles sauberer halten, als einen doppelten Schrägstrich beginnend bei jeder Zeile hinzuzufügen.

Gruppe / Klasse Kommentare

Neben dem Auskommentieren von Funktionen und Schleifen werden Blockbereiche nicht so häufig genutzt. Wo Sie wirklich starke Blockkommentare benötigen , stehen am Anfang Ihrer Backend-Dokumente oder Bibliotheksdateien. Es ist einfach, alles durchzugehen und solide Dokumentation für jede Datei in Ihrer Website zu schreiben - wir können diese Praxis in vielen CMS wie WordPress sehen.

Der oberste Bereich Ihrer Seite sollte Kommentare zur Datei selbst enthalten. Auf diese Weise können Sie schnell überprüfen, wo Sie gerade arbeiten, wenn Sie an mehreren Seiten gleichzeitig arbeiten. Zusätzlich können Sie diesen Bereich als Datenbank für die wichtigsten Funktionen verwenden, die Sie außerhalb der Klasse benötigen .

 / ** * @desc Diese Klasse enthält Funktionen für die Benutzerinteraktion * Beispiele umfassen user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstrakte Klasse myWebClass {} 

Sie können sehen, dass ich nur eine kleine Beispielklasse für den gefälschten myWebClass Code verwendet habe. Ich habe einige Meta-Informationen mit meinem Namen und meiner E-Mail-Adresse für den Kontakt hinzugefügt. Wenn Entwickler Open-Source-Code schreiben, ist dies in der Regel eine gute Vorgehensweise, so dass andere sich möglicherweise an Sie wenden, um Unterstützung zu erhalten. Dies ist auch eine solide Methode, wenn Sie in größeren Entwicklungsteams arbeiten.

Das Tag @required ist nicht etwas, das ich anderswo verwendet habe. Ich habe mit dem Format in einigen meiner Projekte Schritt gehalten, nur auf Seiten, auf denen ich viele Methoden angepasst habe. Immer, wenn Sie Seiten in eine Datei einschließen, müssen sie kommen, bevor Sie einen Code ausgeben. Das Hinzufügen dieser Details in den Hauptklassen-Kommentarblock ist eine gute Möglichkeit, sich daran zu erinnern, welche Dateien benötigt werden .

Front-End-Code-Kommentierung

Nachdem wir nun drei wichtige Kommentarvorlagen behandelt haben, schauen wir uns ein paar andere Beispiele an. Es gibt viele Frontend-Entwickler, die von statischem HTML in jQuery und CSS-Code umgezogen sind. HTML-Kommentare sind im Vergleich zu Programmieranwendungen nicht so zielführend, aber wenn Sie Stilbibliotheken und Seitenskripte schreiben, können die Dinge im Laufe der Zeit unübersichtlich werden.

(Bildquelle: Fotolia)

JavaScript folgt einer eher traditionellen Methode des Kommentierens ähnlich wie Java, PHP und C / C ++. CSS verwendet nur die blockartigen Kommentare, die durch einen Schrägstrich und einen Stern gekennzeichnet sind . Sie sollten sich daran erinnern, dass Kommentare Ihren Besuchern offen angezeigt werden, da weder CSS noch JS serverseitig geparst werden, aber eine dieser Methoden funktioniert hervorragend, um informative Leckerbissen in Ihrem Code zu hinterlassen.

Das Aufbrechen von CSS-Dateien kann eine lästige Pflicht sein. Es ist uns allen bekannt, dass Sie einen Inline-Kommentar hinterlassen, um eine Fehlerbehebung für Internet Explorer oder Safari zu erklären. Aber ich glaube, dass CSS-Kommentare auf der Ebene jQuery und PHP verwendet werden können. Lassen Sie uns in das Erstellen von Stilgruppen eintauchen, bevor Sie einige detaillierte Tipps für das Kommentieren von Code finden.

CSS-Stilgruppen

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

Wenn ich zurück zum Bearbeiten von CSS gehe, finde ich in wenigen Sekunden, was ich brauche. Die Art, wie Sie Stile gruppieren, liegt ganz bei Ihnen, und das ist die Schönheit dieses Systems. Ich habe ein paar voreingestellte Standards, die ich unten skizziert habe:

• @Resets - Entfernen von Standard-Browser-Rändern, Padding, Schriftarten, Farben usw.
• @fonts - Absätze, Überschriften, Blockquotes, Links, Code
• @navigation - die wichtigsten Links zur Kernnavigation
• @layout - Wrapper, Container, Seitenleisten
• @header & @footer - diese können je nach Design variieren. Zu den möglichen Stilen gehören Links und ungeordnete Listen, Fußzeilenspalten, Überschriften und Unternavs

Bei der Gruppierung von Stylesheets kann das Tagging-System sehr hilfreich sein. Im Gegensatz zu PHP oder JavaScript verwende ich jedoch ein einzelnes @ group- Tag, gefolgt von einer Kategorie oder Keywords. Ich habe unten zwei Beispiele aufgeführt, damit Sie ein Gefühl dafür bekommen, was ich meine.

 / ** @group footer * / #footer {Stile ...} 

 / ** @group footer, kleine Schriftarten, Spalten, externe Links ** / 

Sie könnten auch ein paar zusätzliche Details in jedem Kommentarblock hinzufügen. Ich entscheide mich dafür, die Dinge einfach und unkompliziert zu halten, damit die Stylesheets leicht überflogen werden können. Beim Kommentieren dreht sich alles um Dokumentation, so lange du das Schreiben verstehst, es ist gut zu gehen!

4 Tipps zum besseren Kommentar Styling

In der ersten Hälfte dieses Artikels haben wir uns die verschiedenen Formate für die Code-Kommentierung angesehen. Lassen Sie uns nun einige allgemeine Tipps zum sauberen, organisierten und leicht verständlichen Code erläutern.

1. Halten Sie alles lesbar

Manchmal vergessen wir als Entwickler, dass wir Kommentare schreiben, die Menschen lesen können . Alle Programmiersprachen, die wir verstehen, sind für Maschinen entwickelt, so dass es mühsam sein kann, in einfachen geschriebenen Text zu konvertieren. Es ist wichtig zu beachten, dass wir nicht hier sind, um eine Forschungsarbeit auf Hochschulebene zu schreiben, sondern nur Tipps zu hinterlassen !

 function getTheMail () {// code hier erstellt e-mail / * run code wenn unser benutzerdefinierter sendMyMail () Funktionsaufruf true zurückgibt find sendMyMail () in /libs/mailer.class.php wir prüfen, ob der Benutzer alle Felder ausfüllt und Nachricht wird gesendet! * / if (sendMyMail ()) {true zurück; // bleib wahr und zeige den Bildschirm erfolgreich an}} 

Schon ein paar Worte sind besser als nichts . Wenn Sie in der Zukunft wieder Projekte bearbeiten und bearbeiten, ist es oft überraschend, wie viel Sie vergessen werden. Da Sie nicht jeden Tag dieselben Variablen und Funktionsnamen betrachten, vergessen Sie langsam den Großteil Ihres Codes. So können Sie nie zu viele Kommentare hinterlassen ! Aber du kannst zu viele schlechte Kommentare hinterlassen.

Als allgemeine Faustregel nehmen Sie sich vor dem Schreiben etwas Zeit zum Anhalten und Nachdenken . Fragen Sie sich, was das Programm am meisten verwirrt und wie können Sie es am besten in "Dummy" -Sprache erklären ? Überlegen Sie auch, warum Sie den Code genau so schreiben, wie Sie sind .

Einige der verwirrendsten Fehler werden angezeigt, wenn Sie den Zweck von benutzerdefinierten (oder 3rd Party) Funktionen vergessen. Hinterlassen Sie einen Kommentarpfad, der zu einigen anderen Dateien zurückführt, wenn Sie sich dadurch leichter an die Funktionalität erinnern können.

2. Lindere etwas Raum!

Ich kann nicht genug betonen, wie wichtig Whitespace sein kann. Dies gilt in doppelter Hinsicht für PHP- und Ruby-Entwickler, die auf 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 gelangen könnten?

 $ dir1 = "/ home /"; // setze das Haupt-Home-Verzeichnis $ myCurrentDir = getCurDirr (); // Setze das aktuelle Benutzerverzeichnis $ userVar = $ get_username (); // der Benutzername des aktuellen Benutzers 

Im obigen Beispiel werden Sie die zusätzliche Auffüllung bemerken, die ich zwischen den Kommentaren und dem Code in jeder Zeile platziert habe. Wenn Sie durch Dateien blättern, wird diese Art der Kommentierung deutlich hervorgehoben . Es macht das Finden von Fehlern und die Korrektur Ihres Codes um ein Vielfaches einfacher, wenn variable Blöcke so sauber sind .

Sie könnten eine ähnliche Aufgabe für den Code innerhalb einer Funktion ausführen, bei der Sie verwirrt darüber sind, wie es funktioniert, aber diese Methode würde Ihren Code mit Inline-Kommentaren überladen, und das ist das genaue Gegenteil von geordneten! Ich empfehle in diesem Szenario einen großen Block-Line-Kommentar um den Bereich der Logik hinzuzufügen .

 $ (document) .ready (function () {$ ('. sub'). hide (); // Subnavigation ausblenden bei Pageload / ** Suche nach einem click -Ereignis auf einem Anker in .itm div verhindert den Standardlink action, 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 open / close ** / $ ('. itm a') umzuschalten live ('click', function (e ) {e.preventDefault (); $ (this) .parent (). next ('.sub'). slideToggle ('fast');});}); 

Dies ist ein kleiner Teil des jQuery-Codes, der auf eine untergeordnete Navigation ausgerichtet ist. Der erste Kommentar ist inline, um zu erklären, warum wir alle .sub Klassen .sub . Über dem Live-Click-Event-Handler habe ich einen Blockkommentar verwendet und das gesamte Schreiben auf den gleichen Punkt eingerückt . Das macht die Dinge hübscher als laufende Absätze - besonders 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, um hineinzukommen. Niemand möchte nach der Arbeit über sein Programm zurückgehen und jedes Stück dokumentieren. Die meisten von uns wollen nicht einmal zurückgehen und die verwirrenden Bereiche dokumentieren! Es braucht wirklich viel Arbeit.

(Bildquelle: Fotolia)

Aber wenn Sie die Kommentare schreiben können, während Sie programmieren , wird Ihnen alles noch frisch vor Augen stehen . Normalerweise bleiben Entwickler bei einem Problem hängen und durchsuchen das Web nach der einfachsten Lösung. Wenn Sie den Eureka-Moment treffen und ein solches Problem lösen, gibt es im Allgemeinen einen Moment der Klarheit, in dem Sie Ihre vorherigen Fehler verstehen. Dies wäre die beste Zeit, um offene und ehrliche Kommentare zu Ihrem Code zu hinterlassen.

Darüber hinaus wird es Ihnen helfen, sich an das Kommentieren all Ihrer Dateien zu gewöhnen. Die Zeit, die benötigt wird, um zurückzugehen und herauszufinden, wie etwas funktioniert, ist viel größer, nachdem Sie die Funktion bereits erstellt haben. Sowohl dein zukünftiges Selbst als auch deine Teamkollegen werden dir dafür danken, dass sie Kommentare im Voraus hinterlassen haben .

4. Umgang mit Buggy-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 werden sich wahrscheinlich mit Ihrem Code für den Tag trennen müssen, da einige Funktionen noch nicht funktionieren. In diesem Szenario ist es wichtig, dass Sie lange, detaillierte Kommentare darüber hinterlassen, wo Sie die Dinge liegen gelassen haben .

(Bildquelle: Fotolia)

Selbst nach einer erholsamen Nacht können Sie überrascht sein, wie schwierig es sein kann, wieder in den Schwung der Kodierung zu kommen. Wenn Sie beispielsweise eine Bild-Upload-Seite erstellen und diese nicht abgeschlossen haben, sollten Sie einen Kommentar dazu abgeben, an welcher Stelle des Vorgangs Sie aufgehört haben . Werden die Bilder hochgeladen und im temporären Speicher gespeichert? Oder sie werden im Upload-Formular nicht einmal erkannt oder nach dem Hochladen auf der Seite nicht richtig angezeigt.

Das Kommentieren von Fehlern ist aus zwei Hauptgründen wichtig. Zuerst können Sie leicht dort weitermachen, wo Sie aufgehört haben, und es erneut versuchen, um das Problem zu beheben . Und zweitens können Sie zwischen der Live-Version Ihrer Website und dem Testgelände unterscheiden . Denken Sie daran, dass Kommentare verwendet werden sollten, um zu erklären, warum Sie etwas tun, nicht genau, was es tut.

Fazit

Die Entwicklung von Web-Apps und Software ist eine erfüllende, wenn auch schwierige, Praxis. Wenn Sie einer der wenigen Entwickler sind, die Software wirklich verstehen, dann ist es wichtig, mit Ihren Programmierkenntnissen zu reifen. Beschreibende Kommentare zu hinterlassen ist auf lange Sicht nur eine gute Übung, und Sie werden es wahrscheinlich nie bereuen!

Wenn Sie Vorschläge für eine klarere Code-Kommentierung haben, lassen Sie es uns im folgenden Diskussionsbereich wissen!

Vorausschauendes Design: Wenn die Entscheidung aus der Entscheidungsfindung entfernt wird

Haben Sie schon einmal darüber nachgedacht, wie das Web aussehen würde, wenn wir Nutzerbedürfnisse antizipieren könnten ? Die Idee, die Nutzererfahrung zu personalisieren und verschiedenen Personen unterschiedliche Inhalte auf Basis ihrer Interessen anzubieten, taucht in letzter Zeit in den Diskussionen über Webdesign auf.Der

(Tech- und Design-Tipps)

Google-Telefonansage in zwei Schritten jetzt mit weiteren Informationen

Eine der häufigeren Beschwerden, die viele über den zweistufigen Bestätigungsvorgang von Google zur Beschleunigung Ihrer Google Mail-Sicherheit aufgezeigt haben, ist, dass die Eingabeaufforderung nicht wirklich viele Informationen zum Anmeldeversuch enthält. Dies wird nicht mehr der Fall sein, da Google diese Eingabeaufforderungen optimiert und es ihnen ermöglicht, zusätzliche Informationen zum Anmeldeversuch anzuzeigen .Die a

(Tech- und Design-Tipps)