How to Comment in Lua (Single Line and Multi-Line Comments)

Lua is a dynamically typed, minimalist language. It has no formal type annotations, no mandatory docstrings, and no built-in documentation generator. That makes comments the primary mechanism for explaining intent, documenting function signatures, and marking temporary code changes. In a language where a function like `process(x, y, z)` gives no hint about what x, y, and z mean, a single comment line prevents hours of confusion for anyone reading the script later — including yourself.

Comments serve three distinct purposes in real Lua code: documentation (explaining what a function, variable, or module does), annotation (marking the why behind non-obvious logic), and debugging (temporarily disabling code blocks without deleting them). Each purpose calls for a slightly different commenting style.

Where Lua comments are commonly used

• File headers — author, date, module name, and brief description at the top of every script.
• Function documentation — parameter descriptions, return values, and side effects immediately before a function definition.
• Inline annotations — short notes at the end of a line explaining a magic number, a workaround, or a dependency.
• Temporary disabling — wrapping a code block in a block comment to turn it off during development without losing the code.
• TODO / FIXME markers — flagging work in progress or known bugs for later attention.

The single-line comment is the most common form in Lua. It starts with two consecutive hyphens (`--`) and extends to the end of the current line. The interpreter completely ignores everything from `--` to the next newline character.

-- 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

Placement rules

A single-line comment can appear anywhere that whitespace is valid: on its own line, at the end of a statement, or between tokens. The only constraint is that `--` must not appear inside a string literal — inside quotes or long brackets it is treated as literal text, not a comment 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

The double-hyphen convention

Unlike C or JavaScript where `//` is common, Lua uses `--` exclusively. If you come from another language, muscle memory may push you toward `//` or `#`. Neither is a valid comment marker in standard Lua — `//` is a floor division operator in Lua 5.3+ and `#` is the length operator. Always use `--` for line comments.

Multi-line block comments in Lua use the long bracket syntax. A block comment opens with `--[[` and closes with `]]`. The Lua interpreter ignores everything between those two delimiters, including newlines, indentation, and any `--` sequences within the block.

--[[
  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

Long bracket levels for nesting

Standard `--[[ ]]` blocks cannot contain `]]` literally — any `]]` inside the block ends the comment. Lua solves this with bracket levels: you add equal signs between the brackets to create a unique opening/closing pair. A level-1 block uses `--[=[` and `]=]`, level-2 uses `--[==[` and `]==]`, and so on. The closing delimiter must match the opening bracket level exactly.

--[=[
  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.
]==]

Block comment vs. multiple single-line comments

Temporarily disabling a function, loop, or conditional block is one of the most practical uses of comments during development. Lua's block comment syntax makes this clean and reversible — but there is a common pattern that makes it even faster to toggle.

-- 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
--]]

Knowing the syntax is the easy part. Knowing when and how to comment well is what separates maintainable Lua code from a script that is impossible to work with six months later. These practices apply to Lua specifically, though most are universal principles for any dynamically typed language.

Comment the why, not the what

Code already shows what is happening. A comment that says `-- increment i by 1` next to `i = i + 1` adds zero information. Comments earn their place when they explain decisions: why a particular algorithm was chosen, why a limit is set to a specific value, or why a function is called in an unusual order. If the reasoning is clear from the code itself, a comment is optional.

Document function signatures explicitly

Lua has no native type system for documenting parameters. A brief block comment above every public function that lists parameter names, their expected types, and the return value is one of the highest-value commenting habits in Lua. This is especially true for any function consumed by collaborators or exposed in a module.

--[[
  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

Use consistent TODO and FIXME markers

Mark incomplete work with a consistent prefix so you can search for it. `-- TODO:` flags planned improvements, `-- FIXME:` flags known bugs, and `-- HACK:` flags workarounds that need proper solutions later. Most editors and code search tools recognise these prefixes and can filter results to only show flagged lines.

Avoid over-commenting

A script dense with comments for every variable assignment is harder to read, not easier. Comments add visual weight — when every line has one, the important comments get lost in the noise. Aim for a comment density where comments mark genuinely non-obvious choices and document public-facing function contracts, not narrate every operation.

• Do comment: non-obvious algorithm choices, magic numbers with business context, workarounds for known bugs.
• Do not comment: self-explanatory variable names, standard idioms (like `for i = 1, #t do`), and obvious operations.
• Do comment: every function in a shared module with parameter types and return values.
• Do not comment: private helper functions whose purpose is obvious from their name and call site.
• Do comment: the reason for a conditional that is not intuitively obvious from the condition itself.

Roblox uses Luau, a statically typed derivative of Lua 5.1. The comment syntax is identical to standard Lua — `--` for single-line and `--[[ ]]` for multi-line. Luau adds one meaningful extension: the triple-hyphen documentation comment `---`, which the Luau Language Server reads to provide hover documentation, parameter hints, and type information directly inside Roblox Studio.

Luau documentation comments (---)

When you write `---` above a function or variable, the Luau LSP treats the comment as structured documentation. You can annotate parameter types with `@param`, return types with `@return`, and deprecation notices with `@deprecated`. These are not enforced by the runtime — they are read by the language server tooling and shown as tooltips in Studio's script editor.

--- 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

Practical Roblox commenting patterns

In Roblox development, comments serve an additional role: making scripts readable for collaborators who may not have written the original code. Roblox games frequently grow into large codebases maintained by teams, and `--` comments are the primary tool for documenting remote event contracts, module APIs, and the purpose of each LocalScript.

• Remote event contracts — comment what arguments a RemoteEvent or RemoteFunction expects, since the receiver cannot see the caller's code.
• Module API headers — use a `--[[ Module: ... ]]` block at the top of every ModuleScript to describe its purpose and public interface.
• Deprecated code — mark old APIs with `-- @deprecated: use NewFunction() instead` so collaborators know what to avoid.
• Section dividers — use `-- ────────────────── Initialization ──────────────────` style separators to visually partition long scripts into readable zones.

If someone unfamiliar with your codebase opened this script tomorrow, would they understand what each function does without running the game? That is the comment quality bar worth aiming for.

Comments are essential during development, but there are specific scenarios where removing them is the right move: deploying production scripts, obfuscating game code, reducing script file size, or preparing a minified build for a performance- sensitive environment.

Why comments increase script size

In Lua, source files are compiled to bytecode at runtime. Comments are stripped during this compilation step, so they have no impact on bytecode size or execution speed. However, in environments where the source file itself is transferred — such as Roblox Studio replicating scripts to game clients, or a web server serving a Lua config file — the raw text size matters. A heavily commented script can be 20–40% larger than its comment-stripped equivalent.

Removing comments manually vs. using a tool

Manually removing comments is error-prone. It is easy to accidentally delete a closing `]]` that belongs to a string rather than a comment, or leave orphaned comment markers that cause syntax errors. A dedicated comment-removal tool parses the full Lua grammar and understands the difference between a `--` inside a string literal and a `--` that starts a comment. It strips only genuine comments while leaving strings, logic, and structure completely intact.

The Lua Comment Remover on Quasar Tools handles both `--` single-line and `--[[ ]]` multi-line comments in one pass. It runs entirely in your browser — your source code is never uploaded to any server. Paste your script, click remove, and get the cleaned output instantly.

Comment removal in the deployment pipeline

For scripts that go through a build step, comment removal can be combined with other code optimisations. The Lua Minifier strips comments and collapses whitespace in one step — useful when you want both a readable source file (with comments) and a compact deployed version (without them). The Lua Compressor goes further, showing before/after size comparisons so you can measure exactly how much the optimisation saves.

• Development source — keep all comments; use the formatter to maintain readable structure.
• Version control — commit the fully commented source; never commit comment-stripped files as the canonical source.
• Deployed/replicated scripts — strip comments with the comment remover, then optionally minify for size reduction.
• Obfuscated scripts — comments are always removed during obfuscation; no manual step needed.
• Open-source libraries — keep comments in source; optionally provide a minified build in a `/dist` folder.