Как Комментировать в Lua: Однострочные, Блочные и Doc-комментарии Luau

Lua — минималистичный язык с динамической типизацией. В нём нет формальных аннотаций типов, обязательных docstring и встроенного генератора документации. Это делает комментарии основным механизмом для объяснения намерений, документирования сигнатур функций и пометки временных изменений кода. В языке, где функция вроде `process(x, y, z)` не даёт ни малейшего намёка на то, что значат x, y и z, одна строка комментария избавляет от часов путаницы любого, кто позже будет читать скрипт — включая вас самих.

Комментарии выполняют три разные задачи в реальном коде Lua: документация (объяснение того, что делает функция, переменная или модуль), аннотация (пометка причины неочевидной логики) и отладка (временное отключение блоков кода без их удаления). Каждой задаче соответствует свой стиль комментирования.

Где комментарии Lua обычно используются

• Заголовки файлов - автор, дата, имя модуля и краткое описание в начале каждого скрипта.
• Документация функций - описания параметров, возвращаемые значения и побочные эффекты непосредственно перед определением функции.
• Встроенные аннотации - короткие заметки в конце строки, объясняющие магическое число, обходной путь или зависимость.
• Временное отключение - обёртывание блока кода в блочный комментарий для его отключения во время разработки без потери кода.
• Маркеры TODO / FIXME - пометка незавершённой работы или известных багов для последующего внимания.

Однострочный комментарий — самая распространённая форма в Lua. Он начинается с двух последовательных дефисов (`--`) и продолжается до конца текущей строки. Интерпретатор полностью игнорирует всё от `--` до следующего символа перевода строки.

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

Правила размещения

Однострочный комментарий может появиться где угодно, где допустим пробельный символ: на отдельной строке, в конце инструкции или между токенами. Единственное ограничение — `--` не должен появляться внутри строкового литерала: внутри кавычек или длинных скобок он считается литеральным текстом, а не маркером комментария.

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

Конвенция двойного дефиса

В отличие от C или JavaScript, где привычен `//`, Lua использует исключительно `--`. Если вы пришли из другого языка, мышечная память может тянуть вас к `//` или `#`. Ни то, ни другое не является корректным маркером комментария в стандартном Lua — `//` это оператор целочисленного деления в Lua 5.3+, а `#` — оператор длины. Всегда используйте `--` для строчных комментариев.

Многострочные блочные комментарии в Lua используют синтаксис длинных скобок. Блочный комментарий открывается `--[[` и закрывается `]]`. Интерпретатор Lua игнорирует всё между этими двумя разделителями, включая переводы строк, отступы и любые последовательности `--` внутри блока.

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

Уровни длинных скобок для вложенности

Стандартные блоки `--[[ ]]` не могут содержать `]]` буквально — любое `]]` внутри блока завершает комментарий. Lua решает это уровнями скобок: вы добавляете знаки равенства между скобками, создавая уникальную пару открывающего/закрывающего разделителя. Блок уровня 1 использует `--[=[` и `]=]`, уровень 2 — `--[==[` и `]==]`, и так далее. Закрывающий разделитель должен точно соответствовать уровню открывающей скобки.

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

Блочный комментарий против нескольких однострочных

Временное отключение функции, цикла или условного блока — одно из самых практичных применений комментариев во время разработки. Синтаксис блочных комментариев Lua делает это чистым и обратимым — но есть распространённый приём, делающий переключение ещё быстрее.

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

Знать синтаксис — простая часть. Знать, когда и как хорошо комментировать — то, что отличает поддерживаемый код Lua от скрипта, с которым невозможно работать через полгода. Эти практики применимы именно к Lua, хотя большинство из них — универсальные принципы для любого языка с динамической типизацией.

Комментируйте почему, а не что

Код уже показывает, что происходит. Комментарий «`-- увеличиваю i на 1`» рядом с `i = i + 1` не добавляет никакой информации. Комментарии заслуживают место, когда объясняют решения: почему выбран конкретный алгоритм, почему лимит установлен на определённое значение или почему функция вызывается в необычном порядке. Если логика ясна из самого кода, комментарий необязателен.

Явно документируйте сигнатуры функций

В Lua нет нативной системы типов для документирования параметров. Краткий блочный комментарий над каждой публичной функцией со списком имён параметров, их ожидаемых типов и возвращаемого значения — одна из самых ценных привычек комментирования в Lua. Это особенно верно для любой функции, используемой коллегами или экспортируемой модулем.

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

Используйте согласованные маркеры TODO и FIXME

Помечайте незавершённую работу единым префиксом, чтобы её можно было искать. `-- TODO:` помечает запланированные улучшения, `-- FIXME:` — известные баги, а `-- HACK:` — обходные пути, требующие нормальных решений в будущем. Большинство редакторов и средств поиска по коду распознают эти префиксы и могут фильтровать результаты, показывая только помеченные строки.

Избегайте избыточного комментирования

Скрипт, перегруженный комментариями к каждому присваиванию переменной, читать труднее, а не легче. Комментарии добавляют визуальный вес — когда каждая строка ими снабжена, важные комментарии теряются в шуме. Стремитесь к плотности, при которой комментарии помечают действительно неочевидные решения и документируют публичные контракты функций, а не пересказывают каждую операцию.

• Стоит комментировать: неочевидные выборы алгоритмов, магические числа с бизнес-контекстом, обходные пути для известных багов.
• Не стоит комментировать: самопоясняющие имена переменных, стандартные идиомы (вроде `for i = 1, #t do`) и очевидные операции.
• Стоит комментировать: каждую функцию общего модуля с типами параметров и возвращаемыми значениями.
• Не стоит комментировать: приватные вспомогательные функции, назначение которых очевидно из имени и места вызова.
• Стоит комментировать: причину условия, которое неочевидно интуитивно из самого условия.

Roblox использует Luau — статически типизированное ответвление Lua 5.1. Синтаксис комментариев идентичен стандартному Lua — `--` для однострочных и `--[[ ]]` для многострочных. Luau добавляет одно существенное расширение: документирующий комментарий с тройным дефисом `---`, который Luau Language Server читает, чтобы показывать документацию при наведении, подсказки параметров и сведения о типах прямо в Roblox Studio.

Документирующие комментарии Luau (---)

Когда вы пишете `---` над функцией или переменной, LSP Luau трактует комментарий как структурированную документацию. Вы можете аннотировать типы параметров через `@param`, возвращаемые типы через `@return`, а уведомления об устаревании через `@deprecated`. Они не enforced средой выполнения — их читают инструменты language server и показывают как подсказки в редакторе скриптов 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

Практические приёмы комментирования в Roblox

В разработке для Roblox комментарии выполняют дополнительную роль: делают скрипты читаемыми для коллег, которые, возможно, не писали исходный код. Игры Roblox часто вырастают в большие кодовые базы, поддерживаемые командами, и комментарии `--` — основной инструмент документирования контрактов удалённых событий, API модулей и назначения каждого LocalScript.

• Контракты удалённых событий - комментируйте, какие аргументы ожидает RemoteEvent или RemoteFunction, ведь принимающая сторона не видит код вызывающего.
• Заголовки API модулей - используйте блок `--[[ Module: ... ]]` в начале каждого ModuleScript, чтобы описать его назначение и публичный интерфейс.
• Устаревший код - помечайте старые API как `-- @deprecated: use NewFunction() instead`, чтобы коллеги знали, чего избегать.
• Разделители секций - используйте разделители вида `-- ------------------ Initialization ------------------`, чтобы визуально разбивать длинные скрипты на читаемые зоны.

Если завтра кто-то, незнакомый с вашей кодовой базой, откроет этот скрипт — поймёт ли он, что делает каждая функция, не запуская игру? Вот планка качества комментариев, к которой стоит стремиться.

Комментарии незаменимы во время разработки, но есть конкретные сценарии, когда их удаление — правильный шаг: деплой продакшн-скриптов, обфускация игрового кода, уменьшение размера файла скрипта или подготовка минифицированной сборки для чувствительной к производительности среды.

Почему комментарии увеличивают размер скрипта

В Lua исходные файлы компилируются в байткод во время выполнения. Комментарии удаляются на этапе компиляции, поэтому не влияют на размер байткода и скорость выполнения. Однако в средах, где сам исходный файл передаётся — например, когда Roblox Studio реплицирует скрипты на игровые клиенты или веб-сервер отдаёт конфигурационный файл Lua — размер сырого текста имеет значение. Сильно закомментированный скрипт может быть на 20-40% больше своего очищенного от комментариев эквивалента.

Удаление комментариев вручную против инструмента

Ручное удаление комментариев чревато ошибками. Легко случайно удалить закрывающую `]]`, которая относится к строке, а не к комментарию, или оставить осиротевшие маркеры, вызывающие синтаксические ошибки. Специализированный инструмент удаления комментариев парсит полную грамматику Lua и понимает разницу между `--` внутри строкового литерала и `--`, начинающим комментарий. Он удаляет только настоящие комментарии, полностью сохраняя строки, логику и структуру.

Удалитель комментариев Lua от Aback Tools обрабатывает и однострочные `--`, и многострочные `--[[ ]]` комментарии за один проход. Он работает целиком в вашем браузере — ваш исходный код никогда не загружается на сервер. Вставьте скрипт, нажмите удалить и мгновенно получите очищенный результат.

Удаление комментариев в пайплайне деплоя

Для скриптов, проходящих через шаг сборки, удаление комментариев можно объединить с другими оптимизациями кода. Минификатор Lua удаляет комментарии и схлопывает пробелы за один шаг — полезно, когда нужны и читаемый исходник (с комментариями), и компактная деплоенная версия (без них). Компрессор Lua идёт дальше, показывая сравнение размеров до/после, чтобы вы могли точно измерить, сколько экономит оптимизация.

• Исходник для разработки - сохраняйте все комментарии; используйте форматтер для поддержания читаемой структуры.
• Контроль версий - коммитьте полностью закомментированный исходник; никогда не коммитьте очищенные файлы как канонический исходник.
• Деплоенные/реплицированные скрипты - удаляйте комментарии удалителем, затем при желании минифицируйте для уменьшения размера.
• Обфусцированные скрипты - комментарии при обфускации всегда удаляются; ручной шаг не нужен.
• Библиотеки с открытым кодом - сохраняйте комментарии в исходнике; опционально предоставляйте минифицированную сборку в папке `/dist`.