Como Comentar em Lua: Comentários de Linha, de Bloco e Doc de Luau

Lua é uma linguagem minimalista de tipagem dinâmica. Não tem anotações de tipo formais, nem docstrings obrigatórias, nem gerador de documentação embutido. Isso torna os comentários o mecanismo principal para explicar a intenção, documentar assinaturas de funções e marcar mudanças temporárias no código. Em uma linguagem onde uma função como `process(x, y, z)` não dá nenhuma pista sobre o que x, y e z significam, uma única linha de comentário evita horas de confusão para quem ler o script depois — incluindo você.

Os comentários servem a três propósitos distintos em código Lua real: documentação (explicar o que uma função, variável ou módulo faz), anotação (marcar o porquê por trás de lógica não óbvia) e depuração (desativar temporariamente blocos de código sem apagá-los). Cada propósito pede um estilo de comentário ligeiramente diferente.

Onde os comentários em Lua são comumente usados

• Cabeçalhos de arquivo - autor, data, nome do módulo e breve descrição no topo de cada script.
• Documentação de funções - descrições de parâmetros, valores de retorno e efeitos colaterais imediatamente antes da definição da função.
• Anotações em linha - notas curtas no fim da linha explicando um número mágico, uma solução de contorno ou uma dependência.
• Desativação temporária - envolver um bloco de código em um comentário de bloco para desligá-lo durante o desenvolvimento sem perder o código.
• Marcadores TODO / FIXME - sinalizar trabalho em andamento ou bugs conhecidos para atenção posterior.

O comentário de linha é a forma mais comum em Lua. Começa com dois hifens consecutivos (`--`) e se estende até o fim da linha atual. O interpretador ignora completamente tudo do `--` até o próximo caractere de nova linha.

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

Regras de posicionamento

Um comentário de linha pode aparecer em qualquer lugar onde espaço em branco seja válido: em sua própria linha, no fim de uma instrução ou entre tokens. A única restrição é que `--` não deve aparecer dentro de uma string literal — entre aspas ou colchetes longos é tratado como texto literal, não como marcador de comentário.

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

A convenção do hífen duplo

Ao contrário de C ou JavaScript onde `//` é comum, Lua usa `--` exclusivamente. Se você vem de outra linguagem, a memória muscular pode empurrá-lo para `//` ou `#`. Nenhum dos dois é um marcador de comentário válido em Lua padrão — `//` é o operador de divisão de piso no Lua 5.3+ e `#` é o operador de comprimento. Use sempre `--` para comentários de linha.

Comentários de bloco de múltiplas linhas em Lua usam a sintaxe de colchetes longos. Um comentário de bloco abre com `--[[` e fecha com `]]`. O interpretador de Lua ignora tudo entre esses dois delimitadores, incluindo novas linhas, indentação e quaisquer sequências `--` dentro do bloco.

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

Níveis de colchetes para aninhamento

Blocos padrão `--[[ ]]` não podem conter `]]` literalmente — qualquer `]]` dentro do bloco encerra o comentário. Lua resolve isso com níveis de colchetes: você adiciona sinais de igual entre os colchetes para criar um par de abertura/fechamento único. Um bloco de nível 1 usa `--[=[` e `]=]`, o nível 2 usa `--[==[` e `]==]`, e assim por diante. O delimitador de fechamento deve corresponder exatamente ao nível do colchete de abertura.

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

Comentário de bloco vs. vários comentários de linha

Desativar temporariamente uma função, um loop ou um bloco condicional é um dos usos mais práticos dos comentários durante o desenvolvimento. A sintaxe de comentário de bloco do Lua torna isso limpo e reversível — mas existe um padrão comum que torna a alternância ainda mais rápida.

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

Conhecer a sintaxe é a parte fácil. Saber quando e como comentar bem é o que separa código Lua manutenível de um script impossível de trabalhar seis meses depois. Essas práticas se aplicam especificamente a Lua, embora a maioria sejam princípios universais para qualquer linguagem de tipagem dinâmica.

Comente o porquê, não o quê

O código já mostra o que está acontecendo. Um comentário que diz `-- incrementa i em 1` ao lado de `i = i + 1` não agrega informação alguma. Os comentários ganham seu lugar quando explicam decisões: por que um algoritmo específico foi escolhido, por que um limite está fixado em um valor específico ou por que uma função é chamada em uma ordem incomum. Se o raciocínio é claro pelo próprio código, o comentário é opcional.

Documente as assinaturas das funções explicitamente

Lua não tem um sistema de tipos nativo para documentar parâmetros. Um breve comentário de bloco acima de cada função pública listando nomes de parâmetros, seus tipos esperados e o valor de retorno é um dos hábitos de comentário de maior valor em Lua. Isso é especialmente verdade para qualquer função consumida por colaboradores ou exposta em um 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

Use marcadores TODO e FIXME consistentes

Marque o trabalho incompleto com um prefixo consistente para poder buscá-lo. `-- TODO:` sinaliza melhorias planejadas, `-- FIXME:` sinaliza bugs conhecidos e `-- HACK:` sinaliza soluções de contorno que precisarão de soluções adequadas depois. A maioria dos editores e ferramentas de busca de código reconhece esses prefixos e pode filtrar resultados para mostrar apenas as linhas sinalizadas.

Evite o excesso de comentários

Um script denso de comentários para cada atribuição de variável é mais difícil de ler, não mais fácil. Comentários adicionam peso visual — quando cada linha tem um, os comentários importantes se perdem no ruído. Busque uma densidade em que os comentários marquem escolhas genuinamente não óbvias e documentem contratos de funções públicas, sem narrar cada operação.

• Comente: escolhas de algoritmo não óbvias, números mágicos com contexto de negócio, soluções de contorno para bugs conhecidos.
• Não comente: nomes de variáveis autoexplicativos, idiomas padrão (como `for i = 1, #t do`) e operações óbvias.
• Comente: cada função de um módulo compartilhado com tipos de parâmetros e valores de retorno.
• Não comente: funções auxiliares privadas cujo propósito é óbvio pelo nome e pelo ponto de chamada.
• Comente: a razão de um condicional que não seja intuitivamente óbvio a partir da própria condição.

Roblox usa Luau, um derivado de tipagem estática do Lua 5.1. A sintaxe de comentário é idêntica à do Lua padrão — `--` para linha e `--[[ ]]` para múltiplas linhas. Luau adiciona uma extensão significativa: o comentário de documentação de hífen triplo `---`, que o Luau Language Server lê para fornecer documentação ao passar o mouse, dicas de parâmetros e informações de tipo diretamente dentro do Roblox Studio.

Comentários de documentação do Luau (---)

Quando você escreve `---` acima de uma função ou variável, o LSP do Luau trata o comentário como documentação estruturada. Você pode anotar tipos de parâmetros com `@param`, tipos de retorno com `@return` e avisos de descontinuação com `@deprecated`. Eles não são impostos pelo runtime — são lidos pelas ferramentas do language server e exibidos como tooltips no editor de scripts do 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

Padrões práticos de comentário no Roblox

No desenvolvimento Roblox, os comentários servem a um papel adicional: tornar os scripts legíveis para colaboradores que talvez não tenham escrito o código original. Jogos de Roblox frequentemente crescem até virar grandes bases de código mantidas por equipes, e os comentários `--` são a ferramenta principal para documentar contratos de eventos remotos, APIs de módulos e o propósito de cada LocalScript.

• Contratos de eventos remotos - comente quais argumentos um RemoteEvent ou RemoteFunction espera, já que o receptor não pode ver o código do chamador.
• Cabeçalhos de API de módulos - use um bloco `--[[ Module: ... ]]` no topo de cada ModuleScript para descrever seu propósito e interface pública.
• Código descontinuado - marque APIs antigas com `-- @deprecated: use NewFunction() instead` para que colaboradores saibam o que evitar.
• Separadores de seção - use separadores no estilo `-- ------------------ Initialization ------------------` para particionar visualmente scripts longos em zonas legíveis.

Se alguém que não conhece sua base de código abrisse este script amanhã, entenderia o que cada função faz sem executar o jogo? Esse é o padrão de qualidade de comentário que vale a pena buscar.

Comentários são essenciais durante o desenvolvimento, mas há cenários específicos em que removê-los é a decisão certa: implantar scripts de produção, ofuscar código de jogo, reduzir o tamanho do arquivo de script ou preparar uma build minificada para um ambiente sensível a desempenho.

Por que comentários aumentam o tamanho do script

Em Lua, arquivos-fonte são compilados para bytecode em tempo de execução. Os comentários são removidos durante essa etapa de compilação, então não impactam o tamanho do bytecode nem a velocidade de execução. Contudo, em ambientes onde o arquivo-fonte em si é transferido — como o Roblox Studio replicando scripts para clientes do jogo, ou um servidor web servindo um arquivo de configuração Lua — o tamanho do texto bruto importa. Um script muito comentado pode ser 20-40% maior do que seu equivalente sem comentários.

Remover comentários manualmente vs. com uma ferramenta

Remover comentários manualmente é propenso a erros. É fácil apagar acidentalmente um `]]` de fechamento que pertence a uma string em vez de um comentário, ou deixar marcadores de comentário órfãos que causam erros de sintaxe. Uma ferramenta dedicada de remoção de comentários analisa a gramática completa do Lua e entende a diferença entre um `--` dentro de uma string literal e um `--` que inicia um comentário. Ela remove apenas comentários genuínos, deixando strings, lógica e estrutura completamente intactas.

O removedor de comentários Lua da Aback Tools lida com comentários de linha `--` e de múltiplas linhas `--[[ ]]` em uma única passada. Ele roda inteiramente no seu navegador — seu código-fonte nunca é enviado a nenhum servidor. Cole seu script, clique em remover e receba a saída limpa instantaneamente.

Remoção de comentários no pipeline de implantação

Para scripts que passam por uma etapa de build, a remoção de comentários pode ser combinada com outras otimizações de código. O minificador de Lua remove comentários e colapsa espaços em branco em uma etapa — útil quando você quer tanto um arquivo-fonte legível (com comentários) quanto uma versão implantada compacta (sem eles). O compressor de Lua vai além, mostrando comparações de tamanho antes/depois para que você possa medir exatamente quanto a otimização economiza.

• Fonte de desenvolvimento - mantenha todos os comentários; use o formatador para manter a estrutura legível.
• Controle de versão - faça commit do fonte totalmente comentado; nunca faça commit de arquivos sem comentários como fonte canônica.
• Scripts implantados/replicados - remova comentários com o removedor de comentários e, opcionalmente, minifique para reduzir o tamanho.
• Scripts ofuscados - comentários sempre são removidos durante a ofuscação; nenhuma etapa manual é necessária.
• Bibliotecas open source - mantenha comentários no fonte; opcionalmente forneça uma build minificada em uma pasta `/dist`.