Commenter en Lua : Commentaires de Ligne, de Bloc et Doc Luau

Lua est un langage minimaliste à typage dynamique. Il n'a ni annotations de type formelles, ni docstrings obligatoires, ni générateur de documentation intégré. Cela fait des commentaires le mécanisme principal pour expliquer l'intention, documenter les signatures de fonctions et marquer les modifications temporaires de code. Dans un langage où une fonction comme `process(x, y, z)` ne donne aucun indice sur la signification de x, y et z, une seule ligne de commentaire évite des heures de confusion à quiconque relit le script — y compris vous.

Les commentaires remplissent trois fonctions distinctes dans le code Lua réel : la documentation (expliquer ce que fait une fonction, une variable ou un module), l'annotation (marquer le pourquoi d'une logique non évidente) et le débogage (désactiver temporairement des blocs de code sans les supprimer). Chaque fonction appelle un style de commentaire légèrement différent.

Où les commentaires Lua sont couramment utilisés

• En-têtes de fichier - auteur, date, nom du module et brève description en tête de chaque script.
• Documentation de fonctions - descriptions des paramètres, valeurs de retour et effets de bord juste avant la définition d'une fonction.
• Annotations en ligne - notes courtes en fin de ligne expliquant un nombre magique, un contournement ou une dépendance.
• Désactivation temporaire - envelopper un bloc de code dans un commentaire de bloc pour le désactiver pendant le développement sans perdre le code.
• Marqueurs TODO / FIXME - signaler un travail en cours ou des bugs connus pour traitement ultérieur.

Le commentaire de ligne est la forme la plus courante en Lua. Il commence par deux tirets consécutifs (`--`) et s'étend jusqu'à la fin de la ligne en cours. L'interpréteur ignore totalement tout ce qui va de `--` au prochain saut de ligne.

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

Règles de placement

Un commentaire de ligne peut apparaître partout où un espace est valide : sur sa propre ligne, en fin d'instruction ou entre des tokens. La seule contrainte est que `--` ne doit pas apparaître dans une chaîne littérale — entre guillemets ou crochets longs, il est traité comme du texte littéral, pas comme un marqueur de commentaire.

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 convention du double tiret

Contrairement à C ou JavaScript où `//` est courant, Lua utilise exclusivement `--`. Si vous venez d'un autre langage, la mémoire musculaire peut vous pousser vers `//` ou `#`. Aucun des deux n'est un marqueur de commentaire valide en Lua standard — `//` est l'opérateur de division entière en Lua 5.3+ et `#` est l'opérateur de longueur. Utilisez toujours `--` pour les commentaires de ligne.

Les commentaires de bloc multi-lignes en Lua utilisent la syntaxe des crochets longs. Un commentaire de bloc s'ouvre avec `--[[` et se ferme avec `]]`. L'interpréteur Lua ignore tout ce qui se trouve entre ces deux délimiteurs, y compris les sauts de ligne, l'indentation et toute séquence `--` à l'intérieur du bloc.

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

Niveaux de crochets pour l'imbrication

Les blocs standard `--[[ ]]` ne peuvent pas contenir `]]` littéralement — tout `]]` à l'intérieur du bloc termine le commentaire. Lua résout cela avec les niveaux de crochets : vous ajoutez des signes égal entre les crochets pour créer une paire ouverture/fermeture unique. Un bloc de niveau 1 utilise `--[=[` et `]=]`, le niveau 2 utilise `--[==[` et `]==]`, et ainsi de suite. Le délimiteur de fermeture doit correspondre exactement au niveau du crochet d'ouverture.

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

Commentaire de bloc vs. plusieurs commentaires de ligne

Désactiver temporairement une fonction, une boucle ou un bloc conditionnel est l'un des usages les plus pratiques des commentaires pendant le développement. La syntaxe de commentaire de bloc de Lua rend cela propre et réversible — mais il existe un motif courant qui rend la bascule encore plus rapide.

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

Connaître la syntaxe est la partie facile. Savoir quand et comment bien commenter, c'est ce qui distingue un code Lua maintenable d'un script impossible à exploiter six mois plus tard. Ces pratiques s'appliquent spécifiquement à Lua, mais la plupart sont des principes universels pour tout langage à typage dynamique.

Commentez le pourquoi, pas le quoi

Le code montre déjà ce qui se passe. Un commentaire disant `-- incrémente i de 1` à côté de `i = i + 1` n'apporte aucune information. Les commentaires gagnent leur place quand ils expliquent des décisions : pourquoi un algorithme particulier a été choisi, pourquoi une limite est fixée à une valeur précise, ou pourquoi une fonction est appelée dans un ordre inhabituel. Si le raisonnement est clair à partir du code lui-même, le commentaire est optionnel.

Documentez explicitement les signatures de fonctions

Lua n'a pas de système de types natif pour documenter les paramètres. Un bref commentaire de bloc au-dessus de chaque fonction publique listant les noms des paramètres, leurs types attendus et la valeur de retour est l'une des habitudes de commentaire les plus précieuses en Lua. C'est particulièrement vrai pour toute fonction consommée par des collaborateurs ou exposée dans un 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

Utilisez des marqueurs TODO et FIXME cohérents

Marquez le travail incomplet avec un préfixe cohérent pour pouvoir le rechercher. `-- TODO:` signale les améliorations prévues, `-- FIXME:` signale les bugs connus, et `-- HACK:` signale les contournements nécessitant de vraies solutions plus tard. La plupart des éditeurs et outils de recherche de code reconnaissent ces préfixes et peuvent filtrer les résultats pour n'afficher que les lignes signalées.

Évitez le sur-commentage

Un script saturé de commentaires pour chaque affectation de variable est plus difficile à lire, pas plus facile. Les commentaires ajoutent du poids visuel — quand chaque ligne en a un, les commentaires importants se perdent dans le bruit. Visez une densité où les commentaires marquent des choix réellement non évidents et documentent les contrats des fonctions publiques, sans narrer chaque opération.

• À commenter : choix d'algorithmes non évidents, nombres magiques avec contexte métier, contournements de bugs connus.
• À ne pas commenter : noms de variables auto-explicatifs, idiomes standards (comme `for i = 1, #t do`), et opérations évidentes.
• À commenter : chaque fonction d'un module partagé avec les types de paramètres et valeurs de retour.
• À ne pas commenter : fonctions utilitaires privées dont le but est évident par leur nom et leur site d'appel.
• À commenter : la raison d'une conditionnelle qui n'est pas intuitivement évidente à partir de la condition elle-même.

Roblox utilise Luau, un dérivé à typage statique de Lua 5.1. La syntaxe des commentaires est identique à celle de Lua standard — `--` pour une ligne et `--[[ ]]` pour plusieurs. Luau ajoute une extension significative : le commentaire de documentation à triple tiret `---`, que le Luau Language Server lit pour fournir une documentation au survol, des indications de paramètres et des informations de type directement dans Roblox Studio.

Commentaires de documentation Luau (---)

Quand vous écrivez `---` au-dessus d'une fonction ou d'une variable, le LSP Luau traite le commentaire comme une documentation structurée. Vous pouvez annoter les types de paramètres avec `@param`, les types de retour avec `@return` et les avis d'obsolescence avec `@deprecated`. Ils ne sont pas appliqués par le runtime — ils sont lus par l'outillage du serveur de langage et affichés comme infobulles dans l'éditeur de scripts 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

Pratiques de commentaire concrètes dans Roblox

Dans le développement Roblox, les commentaires remplissent un rôle supplémentaire : rendre les scripts lisibles pour des collaborateurs qui n'ont peut-être pas écrit le code original. Les jeux Roblox deviennent fréquemment de grandes bases de code maintenues par des équipes, et les commentaires `--` sont l'outil principal pour documenter les contrats d'événements distants, les API de modules et le but de chaque LocalScript.

• Contrats d'événements distants - commentez les arguments qu'attend un RemoteEvent ou RemoteFunction, car le récepteur ne peut pas voir le code de l'appelant.
• En-têtes d'API de modules - utilisez un bloc `--[[ Module: ... ]]` en tête de chaque ModuleScript pour décrire son but et son interface publique.
• Code obsolète - marquez les anciennes API avec `-- @deprecated: use NewFunction() instead` pour que les collaborateurs sachent quoi éviter.
• Séparateurs de sections - utilisez des séparateurs du style `-- ------------------ Initialization ------------------` pour partitionner visuellement les longs scripts en zones lisibles.

Si quelqu'un qui ne connaît pas votre base de code ouvrait ce script demain, comprendrait-il ce que fait chaque fonction sans lancer le jeu ? Voilà la barre de qualité de commentaire qui mérite d'être visée.

Les commentaires sont essentiels pendant le développement, mais il existe des scénarios précis où les supprimer est le bon choix : déployer des scripts de production, obscurcir du code de jeu, réduire la taille du fichier de script ou préparer une build minifiée pour un environnement sensible aux performances.

Pourquoi les commentaires augmentent la taille du script

En Lua, les fichiers sources sont compilés en bytecode à l'exécution. Les commentaires sont retirés durant cette étape de compilation ; ils n'affectent donc ni la taille du bytecode ni la vitesse d'exécution. Cependant, dans les environnements où le fichier source lui-même est transféré — comme Roblox Studio répliquant des scripts vers les clients du jeu, ou un serveur web servant un fichier de configuration Lua — la taille du texte brut compte. Un script très commenté peut être 20 à 40 % plus grand que son équivalent sans commentaires.

Supprimer les commentaires manuellement vs. avec un outil

Supprimer les commentaires manuellement est source d'erreurs. Il est facile de supprimer accidentellement un `]]` fermant qui appartient à une chaîne plutôt qu'à un commentaire, ou de laisser des marqueurs orphelins qui provoquent des erreurs de syntaxe. Un outil dédié de suppression de commentaires analyse toute la grammaire Lua et comprend la différence entre un `--` à l'intérieur d'une chaîne littérale et un `--` qui débute un commentaire. Il ne retire que les vrais commentaires en laissant chaînes, logique et structure parfaitement intactes.

Le suppresseur de commentaires Lua d'Aback Tools traite à la fois les commentaires de ligne `--` et multi-lignes `--[[ ]]` en une seule passe. Il s'exécute entièrement dans votre navigateur — votre code source n'est jamais téléversé vers un serveur. Collez votre script, cliquez sur supprimer et obtenez le résultat nettoyé instantanément.

Suppression des commentaires dans le pipeline de déploiement

Pour les scripts qui passent par une étape de build, la suppression de commentaires peut se combiner avec d'autres optimisations de code. Le minificateur Lua retire les commentaires et condense les espaces en une seule étape — utile quand vous voulez à la fois un fichier source lisible (avec commentaires) et une version déployée compacte (sans eux). Le compresseur Lua va plus loin, en affichant des comparaisons de taille avant/après pour mesurer précisément ce que l'optimisation économise.

• Source de développement - conservez tous les commentaires ; utilisez le formateur pour maintenir une structure lisible.
• Contrôle de version - commitez la source entièrement commentée ; ne commitez jamais des fichiers sans commentaires comme source canonique.
• Scripts déployés/répliqués - supprimez les commentaires avec le suppresseur, puis minifiez éventuellement pour réduire la taille.
• Scripts obscurcis - les commentaires sont toujours retirés pendant l'obfuscation ; aucune étape manuelle nécessaire.
• Bibliothèques open source - conservez les commentaires dans la source ; fournissez éventuellement une build minifiée dans un dossier `/dist`.