Cómo Comentar en Lua: Comentarios de Una Línea, de Bloque y Doc de Luau

Lua es un lenguaje minimalista de tipado dinámico. No tiene anotaciones de tipo formales, ni docstrings obligatorias, ni generador de documentación integrado. Eso convierte a los comentarios en el mecanismo principal para explicar la intención, documentar firmas de funciones y marcar cambios temporales de código. En un lenguaje donde una función como `process(x, y, z)` no da pista alguna sobre qué significan x, y y z, una sola línea de comentario evita horas de confusión a quien lea el guion después — incluido tú.

Los comentarios cumplen tres propósitos distintos en código Lua real: documentación (explicar qué hace una función, variable o módulo), anotación (marcar el porqué tras una lógica no obvia) y depuración (desactivar temporalmente bloques de código sin borrarlos). Cada propósito pide un estilo de comentario ligeramente diferente.

Dónde se usan comúnmente los comentarios en Lua

• Encabezados de archivo - autor, fecha, nombre del módulo y breve descripción al principio de cada guion.
• Documentación de funciones - descripciones de parámetros, valores de retorno y efectos secundarios justo antes de la definición de la función.
• Anotaciones en línea - notas breves al final de una línea que explican un número mágico, una solución temporal o una dependencia.
• Desactivación temporal - envolver un bloque de código en un comentario de bloque para apagarlo durante el desarrollo sin perder el código.
• Marcadores TODO / FIXME - señalar trabajo en curso o bugs conocidos para atención posterior.

El comentario de una línea es la forma más común en Lua. Comienza con dos guiones consecutivos (`--`) y se extiende hasta el final de la línea actual. El intérprete ignora por completo todo desde `--` hasta el siguiente salto de línea.

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

Reglas de colocación

Un comentario de una línea puede aparecer en cualquier lugar donde el espacio en blanco sea válido: en su propia línea, al final de una sentencia o entre tokens. La única restricción es que `--` no debe aparecer dentro de una cadena literal — entre comillas o corchetes largos se trata como texto literal, no como marcador de comentario.

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

La convención del doble guion

A diferencia de C o JavaScript donde `//` es común, Lua usa `--` exclusivamente. Si vienes de otro lenguaje, la memoria muscular puede empujarte hacia `//` o `#`. Ninguno es un marcador de comentario válido en Lua estándar — `//` es el operador de división de suelo en Lua 5.3+ y `#` es el operador de longitud. Usa siempre `--` para comentarios de línea.

Los comentarios de bloque multilínea en Lua usan la sintaxis de corchetes largos. Un comentario de bloque abre con `--[[` y cierra con `]]`. El intérprete de Lua ignora todo entre esos dos delimitadores, incluidos saltos de línea, indentación y cualquier secuencia `--` dentro del bloque.

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

Niveles de corchetes para anidar

Los bloques estándar `--[[ ]]` no pueden contener `]]` literalmente — cualquier `]]` dentro del bloque termina el comentario. Lua resuelve esto con niveles de corchetes: añades signos igual entre los corchetes para crear un par de apertura/cierre único. Un bloque de nivel 1 usa `--[=[` y `]=]`, el nivel 2 usa `--[==[` y `]==]`, y así sucesivamente. El delimitador de cierre debe coincidir exactamente con el nivel del corchete de apertura.

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

Comentario de bloque vs. varios comentarios de una línea

Desactivar temporalmente una función, bucle o bloque condicional es uno de los usos más prácticos de los comentarios durante el desarrollo. La sintaxis de comentario de bloque de Lua lo hace limpio y reversible — pero hay un patrón común que lo hace aún más rápido de alternar.

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

Conocer la sintaxis es la parte fácil. Saber cuándo y cómo comentar bien es lo que separa el código Lua mantenible de un guion imposible de trabajar seis meses después. Estas prácticas aplican específicamente a Lua, aunque la mayoría son principios universales para cualquier lenguaje de tipado dinámico.

Comenta el porqué, no el qué

El código ya muestra lo que sucede. Un comentario que dice `-- incrementa i en 1` junto a `i = i + 1` no añade información alguna. Los comentarios ganan su lugar cuando explican decisiones: por qué se eligió un algoritmo concreto, por qué un límite se fija en un valor específico o por qué una función se llama en un orden inusual. Si el razonamiento es claro a partir del propio código, el comentario es opcional.

Documenta las firmas de las funciones explícitamente

Lua no tiene un sistema de tipos nativo para documentar parámetros. Un breve comentario de bloque sobre cada función pública que liste nombres de parámetros, sus tipos esperados y el valor de retorno es uno de los hábitos de comentario de mayor valor en Lua. Es especialmente cierto para cualquier función consumida por colaboradores o expuesta en un módulo.

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

Usa marcadores TODO y FIXME consistentes

Marca el trabajo incompleto con un prefijo consistente para poder buscarlo. `-- TODO:` señala mejoras planificadas, `-- FIXME:` señala bugs conocidos y `-- HACK:` señala soluciones temporales que necesitarán soluciones apropiadas después. La mayoría de editores y herramientas de búsqueda de código reconocen estos prefijos y pueden filtrar resultados para mostrar solo las líneas marcadas.

Evita el exceso de comentarios

Un guion denso en comentarios para cada asignación de variable es más difícil de leer, no más fácil. Los comentarios añaden peso visual — cuando cada línea tiene uno, los comentarios importantes se pierden en el ruido. Apunta a una densidad donde los comentarios marquen decisiones genuinamente no obvias y documenten los contratos de funciones públicas, sin narrar cada operación.

• Sí comentar: elecciones de algoritmo no obvias, números mágicos con contexto de negocio, soluciones temporales para bugs conocidos.
• No comentar: nombres de variables autoexplicativos, modismos estándar (como `for i = 1, #t do`) y operaciones obvias.
• Sí comentar: cada función de un módulo compartido con tipos de parámetros y valores de retorno.
• No comentar: funciones auxiliares privadas cuyo propósito es evidente por su nombre y lugar de llamada.
• Sí comentar: la razón de un condicional que no sea intuitivamente obvio a partir de la condición misma.

Roblox usa Luau, un derivado de tipado estático de Lua 5.1. La sintaxis de comentario es idéntica a la de Lua estándar — `--` para una línea y `--[[ ]]` para varias. Luau añade una extensión significativa: el comentario de documentación de triple guion `---`, que el Luau Language Server lee para proporcionar documentación al pasar el ratón, sugerencias de parámetros e información de tipo directamente dentro de Roblox Studio.

Comentarios de documentación de Luau (---)

Cuando escribes `---` sobre una función o variable, el LSP de Luau trata el comentario como documentación estructurada. Puedes anotar tipos de parámetros con `@param`, tipos de retorno con `@return` y avisos de obsolescencia con `@deprecated`. Estos no son aplicados por el runtime — son leídos por las herramientas del servidor de lenguaje y mostrados como tooltips en el editor de guiones de Studio.

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

Patrones prácticos de comentario en Roblox

En el desarrollo de Roblox, los comentarios cumplen un rol adicional: hacer los guiones legibles para colaboradores que quizá no escribieron el código original. Los juegos de Roblox frecuentemente crecen hasta convertirse en bases de código grandes mantenidas por equipos, y los comentarios `--` son la herramienta principal para documentar contratos de eventos remotos, APIs de módulos y el propósito de cada LocalScript.

• Contratos de eventos remotos - comenta qué argumentos espera un RemoteEvent o RemoteFunction, ya que el receptor no puede ver el código del llamador.
• Encabezados de API de módulos - usa un bloque `--[[ Module: ... ]]` al principio de cada ModuleScript para describir su propósito e interfaz pública.
• Código obsoleto - marca APIs antiguas con `-- @deprecated: use NewFunction() instead` para que los colaboradores sepan qué evitar.
• Separadores de sección - usa separadores estilo `-- ------------------ Initialization ------------------` para particionar visualmente guiones largos en zonas legibles.

Si alguien que no conoce tu base de código abriera este guion mañana, ¿entendería qué hace cada función sin ejecutar el juego? Ese es el nivel de calidad de comentario que vale la pena perseguir.

Los comentarios son esenciales durante el desarrollo, pero hay escenarios específicos donde eliminarlos es el movimiento correcto: desplegar guiones de producción, ofuscar código de juego, reducir el tamaño del archivo de guion o preparar una build minificada para un entorno sensible al rendimiento.

Por qué los comentarios aumentan el tamaño del guion

En Lua, los archivos fuente se compilan a bytecode en tiempo de ejecución. Los comentarios se eliminan durante este paso de compilación, así que no impactan el tamaño del bytecode ni la velocidad de ejecución. Sin embargo, en entornos donde el archivo fuente mismo se transfiere — como Roblox Studio replicando guiones a los clientes del juego, o un servidor web sirviendo un archivo de configuración Lua — el tamaño del texto en bruto importa. Un guion muy comentado puede ser un 20-40% más grande que su equivalente sin comentarios.

Eliminar comentarios manualmente vs. con una herramienta

Eliminar comentarios manualmente es propenso a errores. Es fácil borrar accidentalmente un `]]` de cierre que pertenece a una cadena y no a un comentario, o dejar marcadores de comentario huérfanos que causan errores de sintaxis. Una herramienta dedicada de eliminación de comentarios analiza la gramática completa de Lua y entiende la diferencia entre un `--` dentro de una cadena literal y un `--` que inicia un comentario. Elimina solo los comentarios genuinos dejando cadenas, lógica y estructura completamente intactas.

El eliminador de comentarios Lua de Aback Tools maneja tanto comentarios de una línea `--` como multilínea `--[[ ]]` en una sola pasada. Se ejecuta enteramente en tu navegador — tu código fuente nunca se sube a ningún servidor. Pega tu guion, haz clic en eliminar y obtén la salida limpia al instante.

Eliminación de comentarios en el pipeline de despliegue

Para guiones que pasan por un paso de build, la eliminación de comentarios puede combinarse con otras optimizaciones de código. El minificador de Lua elimina comentarios y colapsa espacios en blanco en un paso — útil cuando quieres tanto un archivo fuente legible (con comentarios) como una versión desplegada compacta (sin ellos). El compresor de Lua va más allá, mostrando comparaciones de tamaño antes/después para que puedas medir exactamente cuánto ahorra la optimización.

• Fuente de desarrollo - conserva todos los comentarios; usa el formateador para mantener una estructura legible.
• Control de versiones - haz commit del fuente completamente comentado; nunca committees archivos sin comentarios como fuente canónico.
• Guiones desplegados/replicados - elimina comentarios con el eliminador de comentarios y, opcionalmente, minifica para reducir tamaño.
• Guiones ofuscados - los comentarios siempre se eliminan durante la ofuscación; no se necesita paso manual.
• Librerías de código abierto - conserva los comentarios en el fuente; opcionalmente ofrece una build minificada en una carpeta `/dist`.