Cara Berkomentar di Lua: Komentar Satu Baris, Blok, dan Doc Luau

Lua adalah bahasa minimalis dengan pengetikan dinamis. Ia tidak punya anotasi tipe formal, docstring wajib, atau generator dokumentasi bawaan. Itu menjadikan komentar mekanisme utama untuk menjelaskan maksud, mendokumentasikan tanda tangan fungsi, dan menandai perubahan kode sementara. Dalam bahasa di mana fungsi seperti `process(x, y, z)` tidak memberi petunjuk apa pun tentang arti x, y, dan z, satu baris komentar mencegah kebingungan berjam-jam bagi siapa pun yang membaca skrip itu nanti — termasuk diri Anda sendiri.

Komentar melayani tiga tujuan berbeda dalam kode Lua nyata: dokumentasi (menjelaskan apa yang dilakukan fungsi, variabel, atau modul), anotasi (menandai alasan di balik logika yang tidak jelas), dan debugging (menonaktifkan blok kode sementara tanpa menghapusnya). Setiap tujuan menuntut gaya berkomentar yang sedikit berbeda.

Di mana komentar Lua biasa digunakan

• Header file - penulis, tanggal, nama modul, dan deskripsi singkat di bagian atas setiap skrip.
• Dokumentasi fungsi - deskripsi parameter, nilai kembalian, dan efek samping tepat sebelum definisi fungsi.
• Anotasi inline - catatan singkat di akhir baris yang menjelaskan angka ajaib, solusi sementara, atau dependensi.
• Penonaktifan sementara - membungkus blok kode dalam komentar blok untuk mematikannya selama pengembangan tanpa kehilangan kode.
• Penanda TODO / FIXME - menandai pekerjaan yang sedang berjalan atau bug yang diketahui untuk perhatian selanjutnya.

Komentar satu baris adalah bentuk paling umum di Lua. Ia dimulai dengan dua tanda hubung berurutan (`--`) dan membentang sampai akhir baris saat ini. Interpreter sepenuhnya mengabaikan apa pun dari `--` hingga karakter baris baru berikutnya.

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

Aturan penempatan

Komentar satu baris bisa muncul di mana saja tempat spasi kosong valid: di barisnya sendiri, di akhir pernyataan, atau di antara token. Satu-satunya batasan adalah `--` tidak boleh muncul di dalam literal string — di dalam tanda kutip atau kurung siku panjang, ia diperlakukan sebagai teks literal, bukan penanda komentar.

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

Konvensi tanda hubung ganda

Berbeda dengan C atau JavaScript yang umum memakai `//`, Lua menggunakan `--` secara eksklusif. Jika Anda datang dari bahasa lain, ingatan otot mungkin mendorong Anda ke `//` atau `#`. Keduanya bukan penanda komentar yang valid di Lua standar — `//` adalah operator pembagian lantai di Lua 5.3+ dan `#` adalah operator panjang. Selalu gunakan `--` untuk komentar baris.

Komentar blok multi-baris di Lua menggunakan sintaks kurung siku panjang. Komentar blok dibuka dengan `--[[` dan ditutup dengan `]]`. Interpreter Lua mengabaikan apa pun di antara dua pembatas itu, termasuk baris baru, indentasi, dan urutan `--` apa pun di dalam blok.

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

Level kurung siku panjang untuk nesting

Blok `--[[ ]]` standar tidak bisa memuat `]]` secara literal — setiap `]]` di dalam blok mengakhiri komentar. Lua menyelesaikannya dengan level kurung siku: Anda menambahkan tanda sama dengan di antara kurung untuk membuat pasangan pembuka/penutup yang unik. Blok level-1 menggunakan `--[=[` dan `]=]`, level-2 menggunakan `--[==[` dan `]==]`, dan seterusnya. Pembatas penutup harus sama persis dengan level kurung pembuka.

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

Komentar blok vs. beberapa komentar satu baris

Menonaktifkan sementara fungsi, loop, atau blok kondisional adalah salah satu penggunaan komentar paling praktis selama pengembangan. Sintaks komentar blok Lua membuat ini bersih dan dapat dibalik — tetapi ada pola umum yang membuat togglenya bahkan lebih cepat.

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

Mengetahui sintaks adalah bagian mudah. Mengetahui kapan dan cara berkomentar dengan baik itulah yang membedakan kode Lua yang mudah dirawat dari skrip yang mustahil dikerjakan enam bulan kemudian. Praktik-praktik ini berlaku khusus untuk Lua, meski sebagian besar adalah prinsip universal untuk bahasa pengetikan dinamis mana pun.

Komentari mengapa, bukan apa

Kode sudah menunjukkan apa yang terjadi. Komentar yang berbunyi `-- tambah i dengan 1` di samping `i = i + 1` tidak menambah informasi apa pun. Komentar memperoleh tempatnya saat menjelaskan keputusan: mengapa algoritme tertentu dipilih, mengapa batas diatur ke nilai tertentu, atau mengapa fungsi dipanggil dalam urutan yang tidak biasa. Jika penalarannya jelas dari kode itu sendiri, komentar bersifat opsional.

Dokumentasikan tanda tangan fungsi secara eksplisit

Lua tidak punya sistem tipe bawaan untuk mendokumentasikan parameter. Komentar blok singkat di atas setiap fungsi publik yang mencantumkan nama parameter, tipe yang diharapkan, dan nilai kembalian adalah salah satu kebiasaan berkomentar paling bernilai di Lua. Ini terutama berlaku untuk fungsi apa pun yang dikonsumsi kolaborator atau diekspos dalam modul.

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

Gunakan penanda TODO dan FIXME yang konsisten

Tandai pekerjaan yang belum selesai dengan prefiks yang konsisten agar bisa dicari. `-- TODO:` menandai perbaikan yang direncanakan, `-- FIXME:` menandai bug yang diketahui, dan `-- HACK:` menandai solusi sementara yang kelak butuh solusi proper. Sebagian besar editor dan alat pencarian kode mengenali prefiks ini dan dapat memfilter hasil agar hanya menampilkan baris yang ditandai.

Hindari berkomentar berlebihan

Skrip yang padat komentar untuk setiap penugasan variabel justru lebih sulit dibaca, bukan lebih mudah. Komentar menambah bobot visual — ketika setiap baris punya satu, komentar penting hilang dalam kebisingan. Kejar kepadatan komentar di mana komentar menandai pilihan yang benar-benar tidak jelas dan mendokumentasikan kontrak fungsi publik, bukan menarasikan setiap operasi.

• Patut dikomentari: pilihan algoritme yang tidak jelas, angka ajaib dengan konteks bisnis, solusi sementara untuk bug yang diketahui.
• Jangan dikomentari: nama variabel yang menjelaskan diri sendiri, idiom standar (seperti `for i = 1, #t do`), dan operasi yang jelas.
• Patut dikomentari: setiap fungsi dalam modul bersama dengan tipe parameter dan nilai kembalian.
• Jangan dikomentari: fungsi bantu privat yang tujuannya jelas dari namanya dan lokasi pemanggilannya.
• Patut dikomentari: alasan di balik sebuah kondisional yang tidak intuitif jelas dari kondisinya sendiri.

Roblox menggunakan Luau, turunan Lua 5.1 dengan pengetikan statis. Sintaks komentarnya identik dengan Lua standar — `--` untuk satu baris dan `--[[ ]]` untuk multi-baris. Luau menambahkan satu ekstensi bermakna: komentar dokumentasi tanda hubung tiga `---`, yang dibaca oleh Luau Language Server untuk menyediakan dokumentasi hover, petunjuk parameter, dan informasi tipe langsung di dalam Roblox Studio.

Komentar dokumentasi Luau (---)

Saat Anda menulis `---` di atas fungsi atau variabel, LSP Luau memperlakukan komentar itu sebagai dokumentasi terstruktur. Anda bisa menganotasi tipe parameter dengan `@param`, tipe kembalian dengan `@return`, dan pemberitahuan deprekasi dengan `@deprecated`. Ini tidak ditegakkan oleh runtime — dibaca oleh tooling language server dan ditampilkan sebagai tooltip di editor skrip 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

Pola berkomentar praktis di Roblox

Dalam pengembangan Roblox, komentar melayani peran tambahan: membuat skrip mudah dibaca bagi kolaborator yang mungkin tidak menulis kode aslinya. Game Roblox sering tumbuh menjadi basis kode besar yang dirawat tim, dan komentar `--` adalah alat utama untuk mendokumentasikan kontrak remote event, API modul, dan tujuan setiap LocalScript.

• Kontrak remote event - komentari argumen apa yang diharapkan sebuah RemoteEvent atau RemoteFunction, karena penerima tidak bisa melihat kode pemanggil.
• Header API modul - gunakan blok `--[[ Module: ... ]]` di bagian atas setiap ModuleScript untuk menjelaskan tujuan dan antarmuka publiknya.
• Kode yang dideprekasi - tandai API lama dengan `-- @deprecated: use NewFunction() instead` agar kolaborator tahu apa yang harus dihindari.
• Pemisah bagian - gunakan pemisah bergaya `-- ------------------ Initialization ------------------` untuk mempartisi skrip panjang secara visual menjadi zona yang mudah dibaca.

Jika seseorang yang tidak mengenal basis kode Anda membuka skrip ini besok, apakah ia akan memahami apa yang dilakukan setiap fungsi tanpa menjalankan game? Itulah standar kualitas komentar yang patut dikejar.

Komentar esensial selama pengembangan, tetapi ada skenario spesifik di mana menghapusnya adalah langkah yang tepat: men-deploy skrip produksi, meng-obfuscate kode game, mengurangi ukuran file skrip, atau menyiapkan build minified untuk lingkungan yang sensitif performa.

Mengapa komentar memperbesar ukuran skrip

Di Lua, file sumber dikompilasi ke bytecode saat runtime. Komentar dibuang selama langkah kompilasi ini, sehingga tidak berdampak pada ukuran bytecode atau kecepatan eksekusi. Namun, di lingkungan tempat file sumber itu sendiri ditransfer — seperti Roblox Studio yang mereplikasi skrip ke klien game, atau server web yang menyajikan file konfigurasi Lua — ukuran teks mentah penting. Skrip yang penuh komentar bisa 20-40% lebih besar daripada padanan bebas komentarnya.

Menghapus komentar manual vs. dengan alat

Menghapus komentar secara manual rawan kesalahan. Mudah untuk tidak sengaja menghapus `]]` penutup yang milik string, bukan komentar, atau meninggalkan penanda komentar yatim yang menyebabkan error sintaks. Alat penghapus komentar khusus mem-parse tata bahasa Lua secara penuh dan memahami perbedaan antara `--` di dalam literal string dan `--` yang memulai komentar. Ia hanya membuang komentar asli sembari membiarkan string, logika, dan struktur sepenuhnya utuh.

Penghapus komentar Lua dari Aback Tools menangani komentar satu baris `--` dan multi-baris `--[[ ]]` dalam satu kali jalan. Ia berjalan sepenuhnya di peramban Anda — kode sumber Anda tidak pernah diunggah ke server mana pun. Tempel skrip Anda, klik hapus, dan dapatkan output yang bersih seketika.

Penghapusan komentar di pipeline deployment

Untuk skrip yang melewati tahap build, penghapusan komentar bisa digabung dengan optimisasi kode lain. Minifier Lua membuang komentar dan meringkas whitespace dalam satu langkah — berguna saat Anda ingin sekaligus file sumber yang mudah dibaca (dengan komentar) dan versi ter-deploy yang ringkas (tanpanya). Kompresor Lua melangkah lebih jauh, menampilkan perbandingan ukuran sebelum/sesudah agar Anda bisa mengukur tepat berapa banyak yang dihemat optimalisasi.

• Sumber pengembangan - pertahankan semua komentar; gunakan formatter untuk menjaga struktur yang mudah dibaca.
• Kontrol versi - commit sumber yang penuh komentar; jangan pernah commit file bebas komentar sebagai sumber kanonik.
• Skrip ter-deploy/ter-replikasi - hapus komentar dengan penghapus komentar, lalu opsional minify untuk mengurangi ukuran.
• Skrip ter-obfuscate - komentar selalu dihapus selama obfuscation; tidak perlu langkah manual.
• Library open source - pertahankan komentar di sumber; opsional sediakan build minified di folder `/dist`.