Home » Webdesign lernen » Kommentare im Code: HTML, CSS, JavaScript & PHP

Kommentare in CSS, HTML, JS, PHP & Co.

Praxis, Beispiele & Best‑Practices

Lesezeit: ca. 6 Minuten • Tutorial für Webentwickler und Redakteure

Kommentare sind kurze Hinweise im Quellcode, die Entwicklern Kontext, Absichten und Hinweise geben — ohne die Ausgabe oder Funktion zu beeinflussen. In diesem Tutorial lernst du die Syntax für HTML, CSS/SCSS, JavaScript (inkl. JSDoc), PHP (PHPDoc) und weitere Formate sowie sinnvolle Regeln, wie, wann und warum du kommentierst.

Warum kommentieren?

• Absicht erklären: Warum ist dieser Workaround nötig?
• Dokumentation: APIs, Funktionen, Parameter, expected behaviour.
• Marker: TODOs, FIXME, NOTES für Team‑Aufgaben.
• Debugging: Temporäres Auskommentieren von Code.
• Projektdaten: License, Author, Version, Release‑Hinweise.

Sind Kommentare immer sinnvoll?

Nein. Priorisiere klaren, selbsterklärenden Code. Kommentare sollten das Warum erklären, nicht das Was. Entferne veraltete Kommentare, die irreführen können — ein falscher Kommentar ist oft schlimmer als keiner.

---

1) HTML

Syntax:

<!-- Das ist ein HTML‑Kommentar -->

Tipps

• Keine sensiblen Daten in HTML‑Kommentaren (z. B. Passwörter, interne URLs).
• Nutze Kommentare, um Template‑Zwecke zu erläutern: <!-- Header: Logo + Nav -->.
• Achte auf valide HTML — Kommentare dürfen nicht innerhalb von HTML‑Attribute‑Werten stehen.

---

2) CSS / SCSS

Syntax (CSS / SCSS):

/* Einzeiliger oder mehrzeiliger Kommentar in CSS */

Beispiel:

/* Hauptnavigation: sticky Verhalten */
.header {
  background: #0073aa;
}
/* TODO: responsive padding für mobile */

Tipps

• SCSS unterstützt auch // Kommentare, die beim Kompilieren oft entfernt werden.
• Im Produktions‑Build entfernt ein Minifier Kommentare — achte auf Build‑Konfiguration.
• Kommentare sind ideal für Section‑Trennungen und kurze Erklärungen für Designentscheidungen.

---

3) JavaScript

Syntax:

// Einzeiliger Kommentar
/* Mehrzeiliger Kommentar /

JSDoc‑Beispiel:

/* 
    Addiert zwei Zahlen.
    @param {number} a
    @param {number} b
    @returns {number}
     */
    function add(a, b) {
      return a + b;
    }
       

Tipps

• Nutze JSDoc für öffentliche APIs und Libraries — IDEs und Docs‑Generatoren profitieren davon.
• Vermeide Kommentare als Ersatz für schlechten Code — refactoriere, wenn möglich.
• Build‑Tools / Minifier entfernen Kommentare; JSDoc bleibt für Tools nutzbar.

---

4) PHP

Syntax:

  // Einzeiliger Kommentar
/* Mehrzeiliger Kommentar /
/* 
    PHPDoc / DocBlock für Funktionen, Klassen, Parameter
    @param string $name
    @return void
     */
       

DocBlock‑Beispiel:

    /**
    Lädt benutzerdefinierte Scripts und Styles.
    @return void
     */
    function mein_theme_enqueue() {
      wp_enqueue_style( 'mein-style', get_stylesheet_uri() );
    }
       

Tipps

• Nutze PHPDoc für API‑Dokumentation und bessere IDE‑Unterstützung (phpDocumentor).
• Keine sensiblen Informationen in Kommentaren (DB‑Zugangsdaten, API‑Keys usw.).

---

5) Weitere Formate

• JSON: Standard‑JSON erlaubt keine Kommentare — nutze beim Entwickeln JSONC oder temporäre Schlüssel wie "_comment", entferne aber vor Produktion.
• YAML: Kommentare mit #.
• SQL: einzeilige -- oder mehrzeilige /* ... */.
• Shell / Bash: Kommentare mit #.

---

6) Konventionen & Marker

Gängige Marker:

• TODO: Aufgaben, die noch erledigt werden müssen.
• FIXME: Code, der fehlerhaft ist oder verbessert werden muss.
• NOTE: Wichtige Hinweise oder Hintergrundinfos.
• HACK: Notlösung — immer mit Erklärung und geplanten Refactor‑Hinweis.

Beispiel: /* TODO: Refactor mobile menu - performance issues */

---

7) Security & Datenschutz

• Kommentare sind Teil des ausgelieferten Codes — niemals Passwörter, Tokens oder private URLs dort ablegen.
• Auditiere den Code vor Veröffentlichung und entferne Debug‑Kommentare und Testdaten.

---

8) Tools & Workflows

• Linters: ESLint (JS), Stylelint (CSS), PHPCS (PHP) helfen, Kommentare und Stilprobleme zu finden.
• Doc Generator: JSDoc, phpDocumentor, Typedoc erzeugen API‑Dokumentation aus DocBlocks.
• Build: Webpack, Gulp, Vite — Minifier entfernen Kommentare und optimieren Assets für Produktion.
• IDE: VSCode / PhpStorm Shortcuts (z. B. Ctrl+/) für schnelles Kommentieren.

---

9) Best‑Practices — wann kommentieren?

1. Erkläre das Warum, nicht das Was.
2. Halte Kommentare aktuell — veraltete Hinweise entfernen.
3. Nutze DocBlocks für öffentliche APIs und Bibliotheken.
4. Entferne temporäre Debug‑Kommentare vor Deploy.
5. Verwalte Marker (TODO/FIXME) über Issue Tracker.

---

10) Schnell‑Cheat‑Sheet (Beispiele)

<!-- Header template: Logo + Nav --> 

/* CSS /
 / Section: Header styles
    TODO: mobile padding adjust */ 

/* JS /
// TODO: remove kludge after refactor
/* JSDoc example 

    @param {number} x
    @returns {number}
     */
/** 
    PHPDoc example
    @param array $args
     */

---

Fazit

Kommentare sind ein essenzielles Werkzeug für sauberen, wartbaren Code. Richtig eingesetzt verbessern sie Zusammenarbeit, Onboarding und langfristige Wartbarkeit. Achte auf klare Konventionen, dokumentiere APIs mit DocBlocks und entferne sensible oder veraltete Kommentare vor dem Release.