Kommentieren in Lua: Einzeilige, Block- und Luau-Doc-Kommentare

Lua ist eine dynamisch typisierte, minimalistische Sprache. Es hat keine formalen Typannotationen, keine verpflichtenden Docstrings und keinen eingebauten Dokumentationsgenerator. Das macht Kommentare zum primären Mechanismus, um Absichten zu erklären, Funktionssignaturen zu dokumentieren und temporäre Codeänderungen zu markieren. In einer Sprache, in der eine Funktion wie `process(x, y, z)` keinen Hinweis darauf gibt, was x, y und z bedeuten, verhindert eine einzige Kommentarzeile stundenlange Verwirrung für jeden, der das Skript später liest — einschließlich Ihnen selbst.

Kommentare erfüllen in echtem Lua-Code drei unterschiedliche Zwecke: Dokumentation (erklären, was eine Funktion, Variable oder ein Modul tut), Annotation (das Warum hinter nicht offensichtlicher Logik markieren) und Debugging (Codeblöcke vorübergehend deaktivieren, ohne sie zu löschen). Jeder Zweck erfordert einen etwas anderen Kommentarstil.

Wo Lua-Kommentare üblicherweise eingesetzt werden

• Dateiheader - Autor, Datum, Modulname und kurze Beschreibung am Anfang jedes Skripts.
• Funktionsdokumentation - Parameterbeschreibungen, Rückgabewerte und Nebeneffekte direkt vor der Funktionsdefinition.
• Inline-Annotationen - kurze Notizen am Zeilenende, die eine magische Zahl, einen Workaround oder eine Abhängigkeit erklären.
• Vorübergehende Deaktivierung - einen Codeblock in einen Blockkommentar einpacken, um ihn während der Entwicklung abzuschalten, ohne den Code zu verlieren.
• TODO-/FIXME-Marker - laufende Arbeiten oder bekannte Bugs für spätere Bearbeitung markieren.

Der einzeilige Kommentar ist die häufigste Form in Lua. Er beginnt mit zwei aufeinanderfolgenden Bindestrichen (`--`) und erstreckt sich bis zum Ende der aktuellen Zeile. Der Interpreter ignoriert alles vom `--` bis zum nächsten Zeilenumbruch vollständig.

-- This entire line is a comment
local speed = 150  -- pixels per second

-- TODO: replace magic number with a named constant
local MAX_RETRIES = 5

--[[ This looks like a block comment opener, but only if
     followed immediately by the double bracket ]]
-- The above is two separate single-line comments

Platzierungsregeln

Ein einzeiliger Kommentar kann überall erscheinen, wo Leerraum gültig ist: in einer eigenen Zeile, am Ende einer Anweisung oder zwischen Tokens. Die einzige Einschränkung ist, dass `--` nicht innerhalb eines String-Literals auftreten darf — innerhalb von Anführungszeichen oder Langklammern wird er als literaler Text behandelt, nicht als Kommentar-Marker.

local url = "https://example.com/api--v2"  -- the -- inside the string is NOT a comment
local greeting = "hello"  -- this end-of-line comment IS a comment

if speed > 100 then  -- check speed threshold
  slow_down()
end

Die Doppelbindestrich-Konvention

Anders als in C oder JavaScript, wo `//` üblich ist, verwendet Lua ausschließlich `--`. Wenn Sie aus einer anderen Sprache kommen, kann das Muskelgedächtnis Sie zu `//` oder `#` drängen. Beides ist kein gültiger Kommentar-Marker in Standard-Lua — `//` ist der Floor-Division-Operator in Lua 5.3+ und `#` ist der Längenoperator. Verwenden Sie immer `--` für Zeilenkommentare.

Mehrzeilige Blockkommentare in Lua verwenden die Langklammer-Syntax. Ein Blockkommentar öffnet mit `--[[` und schließt mit `]]`. Der Lua-Interpreter ignoriert alles zwischen diesen beiden Delimitern, einschließlich Zeilenumbrüchen, Einrückung und allen `--`-Sequenzen innerhalb des Blocks.

--[[
  Module: PlayerController
  Author: Dev Team
  Description: Handles player movement, jump mechanics, and ground detection.
  Dependencies: PhysicsEngine, InputMap
]]

local PlayerController = {}

--[[
  Moves the player by the given delta vector.
  @param player  table  The player object
  @param delta   vec2   Movement direction and magnitude
  @return        nil
]]
function PlayerController.move(player, delta)
  player.position = player.position + delta
end

Langklammer-Ebenen zum Verschachteln

Standard-`--[[ ]]`-Blöcke können `]]` nicht literal enthalten — jedes `]]` im Block beendet den Kommentar. Lua löst das mit Klammerebenen: Sie fügen zwischen den Klammern Gleichheitszeichen ein, um ein eindeutiges Öffnungs-/Schließpaar zu erzeugen. Ein Level-1-Block verwendet `--[=[` und `]=]`, Level 2 verwendet `--[==[` und `]==]` und so weiter. Der schließende Delimiter muss genau der Ebene der öffnenden Klammer entsprechen.

--[=[
  This is a level-1 block comment.
  It can safely contain standard --[[ double-bracket ]] syntax
  without ending the outer comment block early.
  Useful when commenting out existing block-commented code.
]=]

--[==[
  Level-2 block comment.
  Can contain both [[ ]] and [=[ ]=] inside it safely.
]==]

Blockkommentar vs. mehrere einzeilige Kommentare

Eine Funktion, Schleife oder einen Bedingungsblock vorübergehend zu deaktivieren ist einer der praktischsten Einsatzfälle von Kommentaren während der Entwicklung. Die Blockkommentar-Syntax von Lua macht das sauber und reversibel — aber es gibt ein verbreitetes Muster, das das Umschalten noch schneller macht.

-- DISABLED: change --[[ to ---[[ to re-enable this block
--[[
local debug_overlay = require("DebugOverlay")
debug_overlay.show_hitboxes = true
debug_overlay.show_fps = true
--]]

-- To enable: change the opening --[[ to ---[[
---[[
local debug_overlay = require("DebugOverlay")
debug_overlay.show_hitboxes = true
debug_overlay.show_fps = true
--]]

Die Syntax zu kennen ist der einfache Teil. Zu wissen, wann und wie man gut kommentiert, unterscheidet wartbaren Lua-Code von einem Skript, mit dem man sechs Monate später nicht mehr arbeiten kann. Diese Praktiken gelten speziell für Lua, wobei die meisten universelle Prinzipien für jede dynamisch typisierte Sprache sind.

Kommentieren Sie das Warum, nicht das Was

Der Code zeigt bereits, was passiert. Ein Kommentar wie `-- erhöhe i um 1` neben `i = i + 1` fügt null Information hinzu. Kommentare verdienen ihren Platz, wenn sie Entscheidungen erklären: warum ein bestimmter Algorithmus gewählt wurde, warum ein Grenzwert auf einen bestimmten Wert gesetzt ist oder warum eine Funktion in ungewöhnlicher Reihenfolge aufgerufen wird. Wenn das Reasoning aus dem Code selbst klar ist, ist der Kommentar optional.

Dokumentieren Sie Funktionssignaturen explizit

Lua hat kein natives Typsystem zum Dokumentieren von Parametern. Ein knapper Blockkommentar über jeder öffentlichen Funktion, der Parameternamen, ihre erwarteten Typen und den Rückgabewert auflistet, ist eine der wertvollsten Kommentar-Gewohnheiten in Lua. Das gilt besonders für jede Funktion, die von Mitarbeitern genutzt oder in einem Modul exponiert wird.

--[[
  Calculates the distance between two 2D points.
  @param x1 number  X coordinate of the first point
  @param y1 number  Y coordinate of the first point
  @param x2 number  X coordinate of the second point
  @param y2 number  Y coordinate of the second point
  @return   number  Euclidean distance between the two points
]]
local function distance(x1, y1, x2, y2)
  local dx = x2 - x1
  local dy = y2 - y1
  return math.sqrt(dx * dx + dy * dy)
end

Verwenden Sie konsistente TODO- und FIXME-Marker

Markieren Sie unvollständige Arbeiten mit einem konsistenten Präfix, damit Sie danach suchen können. `-- TODO:` kennzeichnet geplante Verbesserungen, `-- FIXME:` bekannte Bugs und `-- HACK:` Workarounds, die später richtige Lösungen brauchen. Die meisten Editoren und Code-Suchtools erkennen diese Präfixe und können Ergebnisse so filtern, dass nur markierte Zeilen angezeigt werden.

Vermeiden Sie Überkommentierung

Ein Skript, das für jede Variablenzuweisung dicht mit Kommentaren gespickt ist, ist schwerer zu lesen, nicht leichter. Kommentare fügen visuelles Gewicht hinzu — wenn jede Zeile einen hat, gehen die wichtigen Kommentare im Rauschen verloren. Streben Sie eine Kommentierdichte an, in der Kommentare wirklich nicht offensichtliche Entscheidungen markieren und öffentliche Funktionsverträge dokumentieren, statt jede Operation zu erzählen.

• Doch kommentieren: nicht offensichtliche Algorithmusentscheidungen, magische Zahlen mit Geschäftskontext, Workarounds für bekannte Bugs.
• Nicht kommentieren: selbsterklärende Variablennamen, Standard-Idiome (wie `for i = 1, #t do`) und offensichtliche Operationen.
• Doch kommentieren: jede Funktion eines geteilten Moduls mit Parametertypen und Rückgabewerten.
• Nicht kommentieren: private Hilfsfunktionen, deren Zweck aus Name und Aufrufstelle offensichtlich ist.
• Doch kommentieren: den Grund für eine Bedingung, die nicht intuitiv aus der Bedingung selbst ersichtlich ist.

Roblox verwendet Luau, einen statisch typisierten Ableger von Lua 5.1. Die Kommentarsyntax ist identisch mit Standard-Lua — `--` für einzeilig und `--[[ ]]` für mehrzeilig. Luau fügt eine sinnvolle Erweiterung hinzu: den Dreifachbindestrich-Dokumentationskommentar `---`, den der Luau Language Server liest, um Hover-Dokumentation, Parameterhinweise und Typinformationen direkt in Roblox Studio bereitzustellen.

Luau-Dokumentationskommentare (---)

Wenn Sie `---` über einer Funktion oder Variablen schreiben, behandelt der Luau LSP den Kommentar als strukturierte Dokumentation. Sie können Parametertypen mit `@param`, Rückgabetypen mit `@return` und Deprecation-Hinweise mit `@deprecated` annotieren. Diese werden von der Runtime nicht durchgesetzt — sie werden vom Language-Server-Tooling gelesen und als Tooltips im Skripteditor von Studio angezeigt.

--- Fires a projectile from the given origin in the given direction.
--- @param origin     Vector3  The world position to spawn the projectile
--- @param direction  Vector3  Normalised direction vector
--- @param speed      number   Initial speed in studs per second
--- @return           BasePart The spawned projectile part
local function fireProjectile(origin, direction, speed)
  -- implementation
end

Praktische Roblox-Kommentarmuster

In der Roblox-Entwicklung erfüllen Kommentare eine zusätzliche Rolle: Skripte lesbar zu machen für Mitarbeiter, die den ursprünglichen Code vielleicht nicht geschrieben haben. Roblox-Spiele wachsen häufig zu großen, von Teams gepflegten Codebasen heran, und `--`-Kommentare sind das wichtigste Werkzeug, um Remote-Event-Verträge, Modul-APIs und den Zweck jedes LocalScript zu dokumentieren.

• Remote-Event-Verträge - kommentieren Sie, welche Argumente ein RemoteEvent oder eine RemoteFunction erwartet, da der Empfänger den Code des Aufrufers nicht sehen kann.
• Modul-API-Header - verwenden Sie oben in jedem ModuleScript einen `--[[ Module: ... ]]`-Block, um Zweck und öffentliche Schnittstelle zu beschreiben.
• Veralteter Code - markieren Sie alte APIs mit `-- @deprecated: use NewFunction() instead`, damit Mitarbeiter wissen, was zu vermeiden ist.
• Abschnittstrenner - verwenden Sie Trenner im Stil `-- ------------------ Initialization ------------------`, um lange Skripte visuell in lesbare Zonen zu gliedern.

Wenn jemand, der Ihre Codebasis nicht kennt, dieses Skript morgen öffnen würde: Würde er verstehen, was jede Funktion tut, ohne das Spiel zu starten? Das ist die Kommentar-Qualitätslatte, die es zu erreichen lohnt.

Kommentare sind während der Entwicklung unverzichtbar, aber es gibt konkrete Szenarien, in denen ihre Entfernung der richtige Weg ist: Produktions-Skripte deployen, Spielcode obfuskieren, Skriptdateigröße reduzieren oder eine minifizierte Build für eine performance-sensible Umgebung vorbereiten.

Warum Kommentare die Skriptgröße erhöhen

In Lua werden Quelldateien zur Laufzeit in Bytecode kompiliert. Kommentare werden während dieses Kompilierungsschritts entfernt, haben also keinen Einfluss auf Bytecode-Größe oder Ausführungsgeschwindigkeit. In Umgebungen jedoch, in denen die Quelldatei selbst übertragen wird — etwa wenn Roblox Studio Skripte auf Spielclients repliziert oder ein Webserver eine Lua-Konfigurationsdatei ausliefert —, zählt die Rohtextgröße. Ein stark kommentiertes Skript kann 20-40 % größer sein als sein kommentarbefeites Äquivalent.

Kommentare manuell vs. mit einem Tool entfernen

Manuelles Entfernen von Kommentaren ist fehleranfällig. Es ist leicht, versehentlich ein schließendes `]]` zu löschen, das zu einem String statt einem Kommentar gehört, oder verwaiste Kommentar-Marker zu hinterlassen, die Syntaxfehler verursachen. Ein dediziertes Kommentarentfernungs-Tool parst die vollständige Lua-Grammatik und versteht den Unterschied zwischen einem `--` innerhalb eines String-Literals und einem `--`, der einen Kommentar beginnt. Es entfernt nur echte Kommentare und lässt Strings, Logik und Struktur vollständig intakt.

Der Lua-Kommentar-Entferner von Aback Tools verarbeitet `--`-Einzeiler und `--[[ ]]`-Mehrzeiler in einem Durchgang. Er läuft vollständig in Ihrem Browser — Ihr Quellcode wird nie auf einen Server hochgeladen. Skript einfügen, auf Entfernen klicken und die bereinigte Ausgabe sofort erhalten.

Kommentarentfernung in der Deployment-Pipeline

Für Skripte, die einen Build-Schritt durchlaufen, lässt sich die Kommentarentfernung mit anderen Codeoptimierungen kombinieren. Der Lua-Minifier entfernt Kommentare und verdichtet Leerraum in einem Schritt — nützlich, wenn Sie sowohl eine lesbare Quelldatei (mit Kommentaren) als auch eine kompakte Deployed-Version (ohne sie) wollen. Der Lua-Kompressor geht weiter und zeigt Größenvergleiche vorher/nachher, sodass Sie genau messen können, wie viel die Optimierung spart.

• Entwicklungsquelle - alle Kommentare behalten; den Formatter für lesbare Struktur nutzen.
• Versionskontrolle - die vollständig kommentierte Quelle committen; niemals kommentarbefeite Dateien als kanonische Quelle committen.
• Deployed/replizierte Skripte - Kommentare mit dem Entferner entfernen, dann optional zur Größenreduktion minifizieren.
• Obfuskierte Skripte - Kommentare werden bei der Obfuskation immer entfernt; kein manueller Schritt nötig.
• Open-Source-Bibliotheken - Kommentare in der Quelle behalten; optional eine minifizierte Build in einem `/dist`-Ordner bereitstellen.