Frage von MatheNico, 80

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

Ich programmiere zurzeit meine eigene Website nur zu einem professionellen Programmierer gehören Kommentare natürlich dazu. Nur in der Schule haben wir das nicht vernünftig durchgenommen. Ich brauche hilfe dabei wie ich dieses halt vernünftig kommentiere. Vielen Dank im vorraus

Antwort
von MonkeyKing, 29

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.

Kommentar von fluffiknuffi ,
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.

Kommentar von WhiteGandalf ,

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.

Antwort
von dertechie, 4

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
von tWeuster, 13

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
von RakonDark, 32

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
von Bujin, 34

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. 

Kommentar von RakonDark ,

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 .

Kommentar von MonkeyKing ,

So ist es.

Kommentar von Bujin ,

Also sollte man den Code für jede Software deiner Meinung nach veröffentlichen? Hast du schon mal wochenlang an einem Solver gesessen? Ich denke nicht.. 

Kommentar von fluffiknuffi ,
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.

Antwort
von fluffiknuffi, 8

- 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
von Vyled, 29

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

Ein Professioneller Programmierer versteht Code auch meist so.

Kommentar von RakonDark ,

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 .

Kommentar von Vyled ,

Komisch, ich versteh das meist wenn ich weiß worums geht...

Normal macht man ein Projekt, wo man vorher weiß was getan werden muss und worum das Projekt geht. Und wenn es gut Programmiert ist, versteht man recht schnell auch wie das aufgebaut ist und fuchst sich da rein. 

Bisher habe ich in über 10 Jahren noch nie ein Code gesehen der mehr Dokumentations- hat als Programmzeilen, aber gut, muss ja jeder selbst wissen ob er Arbeiten und Programmieren will oder ein Roman lesen will.

Und wie gesagt, wenn dann würde ich kurze Infos hineinschreiben, aber keine richtige Ausführung, diese wenn dann extra als Dokumentation

Kommentar von RakonDark ,

komisch ist das du solche aussagen machst , ich kenne z.b. kein open source wo man deiner logik folgen würde .

und im berufsleben kenn eich nur schlechte programmierer die sich die zeit ersparen damit sie nicht ausgetauscht werden können .

schon bei der menge an funktionen sollte es eine übersicht geben von variablen , rükgabe werten und eingangswerten , auch wenn viele dinge sich aus dem variablen namen ergeben so ist eine dokumentation unumgänglich .

wer das nciht macht ist halt hobby styler .

p.s. von sich auf profis schliessen ist irgendwie das unprofessionellste was man machen kann .

p.p.s. beteilige dich doch mal an einigen größeren projekten und vielleicht mal bei c++ um dann zu merken das es ohne dokumentation nach 5 jahren bestimmt nicht mehr klappt . geschweige den wenn ein anderer das mal übernehmen oder warten soll .

bei meinen eigenen projekten kannich sagen das nach 500 funktionen der überblick schon nach 1er woche futsch ist , aber ich dokumentiere meine sachen ja auch .

Kommentar von Vyled ,

Ich sag ja Dokumentieren gut aber im Code würde ich es bei Stichwörtern lassen.

An größeren Projekten beteiligen? Achso okay, weil du ja auch weißt wo ich schon meine Finger mit im Spiel hatte. Stimmt... 

Außerdem rede ich nicht von Profi oder sonst was, sondern einfach davon, das man das meiste an Code so versteht und wenn nicht es dann immer noch eine extra Doku gibt. Aber die ganze Code Dateien mit Doku voll zu hauen ergibt für mich wenig Sinn.

Aber muss ja am Ende jeder selbst wissen. Ich kam bisher mit den meisten Open Source klar, auch wenn da nur eine extra Doku war ohne Doku im Code selbst.

Kommentar von fluffiknuffi ,

Ihr habt beide teilweise recht. Ja, man versteht den Code, aber Spaß macht's keinen und es kann enormer zusätzlicher Zeitaufwand sein und für Frust und Fehler sorgen (wenn man den Code eben doch nicht verstanden hat, weil er Dinge tut, die mit Dingen weit außerhalb des aktuellen Kontext zu tun haben).

Ich muss mich mit unkommentiertem/dokumentierten, schlechtem Code täglich herumschlagen und ja, klar es geht irgendwie - aber es macht null Spaß. Es dauert teilweise unfassbar lang.

Kommentar von MonkeyKing ,

Das kommt von jemandem, der noch nicht einmal Kommata richtig setzen kann..

Kommentar von Vyled ,

Stimmt :) Macht ja auch soviel aus... und solche Aussagen kommen von jemanden, der nicht mal Komma richtig schreiben kann

Kommentar von MonkeyKing ,

Ok das war unter der Gürtellinie, ich nehme es zurück. Die Behauptung dass man mehr Zeit zum Dokumentieren als zum programmieren verwenden sollte kann ich aber nur deutlich widersprechen. 

Kommentar von Vyled ,

Das habe ich nicht gesagt. Ich habe gesagt das es für mich kein Sinn ergeben würde, soviel Doku in den Code selbst mit einzubeziehen. Natürlich kann das jeder machen wie er will und schlimm wäre es jetzt auch nicht zwingend, sinnvoller finde ich aber einfach eine extra Dokumentation die dazugelegt wird und höchstens kleine Infos im Code selbst als Doku Info oder sonst was.

Und für große Dinge sind Dokus sicher wichtig aber nicht in dem Code selber... das habe ich noch nie gesehen, höchstens kleine Hinweise oder sowas. 

Wenn dort ein Hinweis steht und ich ja im normalfall weiß, was das für ein Projekt ist, dann verstehe ich das in 90% der fällen auch so, was mit der Funktion gemeint ist.

Kommentar von tWeuster ,

generell gilt , dass man nichts generell sagen kann

Keine passende Antwort gefunden?

Fragen Sie die Community