Wie kann ich PHP,CSS und HTML Code vernünftig kommentieren, so dass ich das immernoch in 5 Jahren verstehe?

... komplette Frage anzeigen

7 Antworten

Gut programmierter Code ist seine eigene Dokumentation und benötigt eigentlich keine weiteren Kommentare. Trotzdem ist es manchmal hilfreich bei besonders komplizierten Funktionen einen Kommentar hinzuzufügen. Bei HTML und CSS halte ich Code größtenteils für unnötig. Höchstens um verschiedene Bereiche voneinander zu trenne, z.B. könntest du im CSS Code einen Bereich für globale Styles haben und einen für jeden Unterbereich (wobei sich auch empfiehlt das in mehreren Dateien aufzuteilen).
Für PHP gibt es den quasi Standard PHPDoc. Das ist schon mal ein guter Ansatzpunkt - jeder Funktion sollte einen kleinen Kommentarblock haben in dem kurz die Funktion beschrieben wird, die Argumente die übergeben und der Rückgabewert. Bei komplizierteren Funktionen kann man schon mal (wie oben geschrieben) einen längeren Erklärtext hinzuschreiben. Du kannst dann mit den richtigen Tools aus wenn du dem PHPDoc Standard folgst automatisch eine Dokumentation für dein Projekt erstellen.

Antwort bewerten Vielen Dank für Deine Bewertung
Kommentar von fluffiknuffi
12.02.2016, 13:45
Gut programmierter Code ist seine eigene Dokumentation und benötigt eigentlich keine weiteren Kommentare.

Manchmal schon. Z. B. wenn es in die Richtung mathematischer Algorithmen geht. Wenn da nur noch Formeln heruntergerasselt werden dann kann es schon mal sein, dass man keine Ahnung hat, warum nun dies und jenes berechnet wird. Auch wenn Variablen "sprechend" benannt werden.

0
Kommentar von WhiteGandalf
12.02.2016, 14:23

Kann mich dem Statement nicht anschließen: Die Ideen, die verursachend und definierend für ein Projekt sind, werden im Quellcode NIEMALS durch den Code selbst widergespiegelt. Der Code (Variablen- und Funktionsnamen) selbst kann bestenfalls die zur Implementation dieser Ideen genutzten Techniken halbwegs unterstützend nahebringen. Aber schon beim GRUND, WARUM man nun ausgerechnet diese Techniken auf diese Weise eingesetzt hat, hört diese Unterstützung auf.

Was aber sowohl für den Programmierer selbst als auch für eine Zusammenarbeit mit anderen Leuten und/oder zu späteren Zeiten zwingend notwendig ist, ist das Dokumentieren eben dieser sämtlicher Ideen, die hinter den Konstrukten stecken. Sonst werden genau diese bei jeder Revision aufs neue erfunden und vergleichend und beurteilend durchgekaut werden müssen. Oder erst mühseelig beim Debuggen immer wieder aufs neue über Versuch und Irrtum erkannt werden müssen. Die Antwort von tWeuster ist da sehr viel zielführender.

0

Was CSS angeht, so empfehle ich Dir die Nutzung von SASS. Da gibt es zwei Arten von Kommentaren:

Multiline, der im CSS erhalten bleibt, so lange nicht der compressed output mode gesetzt ist

/* my comment 
line2
*/

Singleline, der nicht im CSS erhalten bleibt, aber als Kommentar für Entwickler natürlich in SASS sichtbar ist:

// my comment

Außerdem gibt es noch Kommentare, die auch im compressed output erhalten bleiben, z.B. für Lizenzinformationen:

/*! normalize.css v3.0.3 | MIT License | github.com/necolas/normalize.css */

Die Nutzung von SASS ist allerdings für Einsteiger oft mit ein paar Hürden verbunden, weil diverse Vorbereitungen zu treffen sind, damit SASS effizient genutzt werden kann. Z.B. hilft es gulp dafür einzusetzen, dessen Einrichtung und Konfiguration für Einsteiger auch etwas kompliziert und zeitraubend sein kann.

Links:

Für reines CSS gilt ansonsten:

/* My css comment
line2
*/
Antwort bewerten Vielen Dank für Deine Bewertung

Ergänzend zu der Top Antwort von MonkeyKing:

Wenn du ein neues Projekt startest empfiehlt es sich die Ideen bzw. das Konzept irgendwo zu erfassen (Textdateien). Vor allem die User Interaktionen würde ich im Detail erfassen.

Wenn du das gescheit machst, hast du nicht nur eine gute Dokumentation, sondern auch noch eine Testanweisung, die du wiederum mit Unittests ala Silenium abwickeln könntest.

Auch Idee die man nicht realisiert würde ich erfassen. Somit minimiert man die Gefahr etwas zu entwickeln was eigentlich schon längst vom Tisch ist, aber z.B. durch einen Mitarbeiter wieder auf die Agenda geführt wird.

Im Idealfall würde es dann sogar Querverweise zwischen Textdatei und Quellcode Dokumentation geben. Beispiel:

In Textdatei steht: 3.3.4 Löschen via Ajax (/js/formular <- Ordner) und dann kommt die Beschreibung was genau passieren soll

In der JS Datei (/js/formular/main_function.js) steht: #Löscht Eintrag via Ajax (3.3.4) und dann kommt die Funktion die das erledigt

Somit würde sich die Einarbeitung eines neuen Mitarbeiters verkürzen, da die Struktur ebenfalls ersichtlich wäre.

Antwort bewerten Vielen Dank für Deine Bewertung

- Beschränkte dich auf Kommentare, die "wichtiges" erklären. Wichtig ist z. B. nicht das hier:

zahl = zahl + 1; // Eins addieren
text = readTextFromFile('test.txt'); // Text einlesen

Grundsätzlich sollte man nicht kommentieren, was native Funktionen/Befehle der Programmiersprache tun. Außnahme eventuell, wenn sie sehr exotisch sind, wobei dann auch wieder die Frage aufkommt, ob man sie wirklich benutzen sollte.

- Es wird häufig gesagt, man soll eher kommentieren warum man etwas macht, nicht was man macht. Letzteres kann man dem Code ja mehr oder weniger gut entnehmen. Aber warum nun irgendwo in einer langen Berechnung etwas addiert wird, das kann man vielleicht nach einem Jahr nicht mehr so genau sagen.

- Sprechende Variablen-/Methodennamen. Sowas wie i als Zählervariable in einer for-Schleife hat sich eingebürgert aber ansonsten sollte man versuchen, aussagekräftige Variablen-/Methodennamen zu verwenden, weil man sich dann Kommentare sparen kann.

- Als Erweiterung davon kann es auch helfen, Code in Methoden/Funktionen auszulagern - einfach nur um die Lesbar/Verständlichkeit des Codes zu erhören (und nicht zum Zwecke der Wiederverwendbarkeit o. ä.). Wobei ich das persönlich selten mache.

Antwort bewerten Vielen Dank für Deine Bewertung

Hi der "normale" HTML/CSS/Javascript Website Code ist für jeden einsehbar und das bedeutet die Kommentare die du dir selbst schreibst, sieht auch jeder andere. Nun ist die Frage ob du wirklich willst dass alle deinen Code verstehen? Es gibt zB. Tools im Netz mit denen man seinen Code absichtlich unglaublich hässlich wandeln kann "uglify" damit er schwieriger zu lesen ist und Leute deshalb weniger oft Code klauen. 

Code-Klau ist im Netz leider nicht ungewöhnlich was bei PHP natürlich nicht der Fall ist. Von daher würde ich dir wenn überhaupt nur dazu raten Kommentare in PHP zu schreiben. 

<?php #Dies ist ein Kommentar den nur ich auf meinem PC sehe ?>

So siehst nur du sie wenn du das denn so willst. Deine html Datei musst du natürlich dann entsprechend "index.php" nennen und nicht "index.html". 

Dazu kommt dass PHP nur vom Server interpretiert wird und du deine Seite nicht auf deinem PC selbst testen kannst. Das weißt du aber sicher bereits nehme ich mal an. Du musst die Seite also erst uploaden bevor du sie dir angucken kannst. 

Antwort bewerten Vielen Dank für Deine Bewertung
Kommentar von RakonDark
12.02.2016, 13:02

lol , da schüttel ich den kopf , als würde man sooo tolle dinge produzieren das sie geheim bleiben sollen ... aber jeder nutz schön gratis bootstrap jquery etc ... tuen alle so als würden sie gravitationswellen entdecken und haben angst das andere den nobelpreis abfischen .

ich lach mich schlapp , das meiste was der normale programmierer im js produziert, gibt es wohl schon zu 1000 fach im netzt , bzw hat er sich selber bei anderen bedient .

übrigens gibt es auch eine möglichkeit zu dokumentieren und danach die dokumentationen zu entfernen um es in den produktiven einsatz zu bringen , aber ohne dokumentation wird ein JS nicht gerade freundlicher nach ein paar jahren .

1
Kommentar von fluffiknuffi
12.02.2016, 13:52
der "normale" HTML/CSS/Javascript Website Code ist für jeden einsehbar und das bedeutet die Kommentare die du dir selbst schreibst, sieht auch jeder andere. Nun ist die Frage ob du wirklich willst dass alle deinen Code verstehen

Stimmt schon. Aber wie schon gesagt wurde, grundsätzlich gibt es die Tools, die Code entfernen. In der Praxis hast du z. B. den JS-"Source"-Code dann in einem nichtöffentlichen Verzeichnis, und dann kommt z. B. Grunt mit entsprechenden Plugins (z. B. ein Plugin zum Minifizieren) und erzeugt dann eine (oder mehrere) JS-Dateien im öffentlichen JS-Ordner.

Und ich würde dann doch bei größeren Projekten dazu raten, zum einen spart man natürlich Traffic weil das Minifizier-Plugin ja nicht nur Kommentare entfernt und somit die Dateigrößen verkleinert. Zum anderen sind bei größeren, anspruchsvolleren JS-Projekten natürlich Kommentare geboten! Nicht wenn man nur ein paar Fremdbibliotheken einbinden & initialisiert und ein paar jQuery-Effekte benutzt - aber bei umfangreicherem, komplexerem JS-Code durchaus.

0

Dokumentation als extra Datei oder im Code kommentieren bei wichtigen Punkten.

Ein Professioneller Programmierer versteht Code auch meist so.

Antwort bewerten Vielen Dank für Deine Bewertung
Kommentar von RakonDark
12.02.2016, 12:46

was für ein unsinn , ein richtiger programmierer versteht die befehle aber nicht unbedingt den zweck , sowas sagen nur leute die mit dokumentations und projekt arbeit sich nie beschäftigt haben ,

generell gilt , mehr dokumentationszeilen als programmzeilen .

0

ich empfele doxygen als dokumentierungsübersichts tool .

bzw javadocs oder sciptdocs etc ...

schau mal http://webkrauts.de/artikel/2007/stylesheets-kommentieren-mit-cssdoc

ansonsten ist natürlich bei html

<!-- Dokumentierung 
mehrere zeilen
-->

css und js und php

/* dokumentierung 
merhere zeilen */
// dokumentierung am zeilenende
Antwort bewerten Vielen Dank für Deine Bewertung

Was möchtest Du wissen?