コメント（-- と --[[ ]]）

-- 一行コメントです。-- 以降、行末までがコメントになります。

local count = 10  -- 行末コメントです。コードの右側に短い補足を添えます。

--[[
ブロックコメントです。
--[[ から ]] までの範囲がコメントになります。
複数行にわたるコメントを書くときに使います。
]]

--[==[
イコール記号を2つ使ったブロックコメントです。
]] を含む文字列をコメントに含めたいときに使います。
コメント終了は ]==] です。
]==]

種類	書き方	概要
一行コメント	-- テキスト	『--』以降、行末までがコメントになります。行頭・行末どちらに置いても使えます。
ブロックコメント（レベル0）	--[[ ... ]]	複数行にまたがるコメントです。『--[[』で始まり『]]』で終わります。『]]』を含む文字列をコメントに入れることはできません。
ブロックコメント（レベルN）	--[=*[ ... ]=*]	イコール記号をN個はさんだ長括弧記法です。開始と終了のイコール数が一致していれば、コメント内に通常の『]]』を含められます。

Luaの長括弧記法（long bracket）は、コメントだけでなく文字列リテラルにも使われる構文です。開き括弧（『[』）と閉じ括弧（『]』）の間にイコール記号を同じ数だけ挟むことで「レベル」を指定します。コメントの場合は先頭に『--』を付けます。

レベル	開き	閉じ	例
レベル0	[[	]]	--[[ コメント ]]
レベル1	[=[	]=]	--[=[ コメント ]=]
レベル2	[==[	]==]	--[==[ コメント ]==]
レベルN	[===...=[	]===...=]	イコールをN個

コメント内に『]]』という文字列を含めたい場合は、レベル1以上を使います。レベル1のコメント（『--[=[...]=]』）は『]]』を含められますが、『]=]』は含められません。実際のユースケースとしては、コード全体を一時的にコメントアウトする際に内部の文字列と衝突を避けるために高レベルを選ぶことがあります。

判断	場面	理由
書くべき	「なぜこう実装したか」の理由	コードを読むだけではわからない設計意図やトレードオフを残しておくと、将来の自分や他の開発者が助かります。
書くべき	複雑なアルゴリズムや計算式	何をしているか一見でわかりにくい処理には、動作の概要を補足します。
書くべき	公開API・モジュールの関数	引数・戻り値・副作用を関数の直前にコメントで記述しておくと、利用者が読みやすくなります。
書くべき	デバッグ中の一時的な無効化	コメントアウトした理由や期限を残しておくと、後で削除し忘れるリスクが減ります。
書かなくてよい	コードを読めば明らかな処理	自明な説明はノイズになります。変数名・関数名をわかりやすくすれば不要になります。
書かなくてよい	変更履歴・削除したコード	バージョン管理（git）があるため、コメントに古いコードや変更日を残す必要はありません。

一行コメントとブロックコメントの基本的な使い方です。

comment_basic.lua

-- 点数データを集計するサンプルです。

local scores = {85, 92, 78, 95, 61}  -- テスト結果の点数テーブルです。

--[[
  scores テーブルの合計と平均を計算します。
  Lua の # 演算子でテーブルの要素数を取得します。
]]

local total = 0
local count = #scores  -- テーブルの要素数です。

for i = 1, count do
    total = total + scores[i]
end

local average = total / count  -- 平均点を算出します。

print(string.format("Count : %d", count))
print(string.format("Total : %d", total))
print(string.format("Average: %.1f", average))

実行すると次のように出力されます。

$ lua comment_basic.lua
Count : 5
Total : 411
Average: 82.2

長括弧記法のレベルを変えてコメント内に『]]』を含める例です。

comment_bracket_level.lua

--[=[
  レベル1の長括弧コメントです。
  コメント内に ]] を含めても終了しません。
  終了するのは ]=] が現れたときだけです。
]=]

--[==[
  レベル2の長括弧コメントです。
  ]] も ]=] も含めることができます。
  終了するのは ]==] が現れたときだけです。
]==]

-- 長括弧コメントでコードブロックを一時的に無効化する例です。
--[[
local result = heavy_computation()
print(result)
]]

print("active code")

実行すると次のように出力されます。

$ lua comment_bracket_level.lua
active code

関数のドキュメントコメントを書く慣習的なスタイルです。

comment_function.lua

-- calculateAverage: 数値テーブルの平均を計算します。
-- @param values  数値の配列テーブルです。空テーブルは不可。
-- @return        平均値（number）を返します。
-- @error         values が空の場合は nil と エラーメッセージを返します。
local function calculateAverage(values)
    local count = #values
    if count == 0 then
        return nil, "empty table"
    end

    local total = 0
    for _, v in ipairs(values) do
        total = total + v
    end

    return total / count
end

local avg, err = calculateAverage({10, 20, 30, 40, 50})
if err then
    print("Error: " .. err)
else
    print(string.format("Average: %.1f", avg))
end

local avg2, err2 = calculateAverage({})
if err2 then
    print("Error: " .. err2)
end

実行すると次のように出力されます。

$ lua comment_function.lua
Average: 30.0
Error: empty table

Luaのコメントは一行コメント（『--』）とブロックコメント（長括弧記法）の2種類です。一行コメントはコードの右側に補足を添えるときや、処理を1行だけ無効化するときに使います。

ブロックコメントは長括弧記法（『--[[...]]』）を使います。コメント内に通常の『]]』を含めたい場合は、イコール記号を挟んだ高レベルの長括弧（『--[=[...]=]』や『--[==[...]==]』）を使います。開きと閉じのイコール数が一致していないとコメントが正しく終了しません。

Luaには公式のドキュメントコメント形式がありませんが、『--』による一行コメントに『@param』『@return』などのタグを付ける慣習が使われることがあります。LDoc（Lua Documentation Tool）を使うとこれらのコメントからHTMLドキュメントを生成できます。

ブロックコメントの開始と終了のイコール数が一致しない

長括弧記法では開始（『--[==[』）と終了（『]==]』）のイコール数が一致していなければなりません。数が違うとコメントが終了せず、後続のコードがコメントとして扱われます。

--[==[
  このブロックコメントはレベル2です。
]=]   -- NG: ]=] はレベル1の閉じ括弧。レベル2は ]==] で閉じる必要があります。

print("ここには到達しません")  -- コメントの外に出ていないため実行されません。

修正後:

bracket_ok.lua

--[==[
  このブロックコメントはレベル2です。
]==]   -- OK: イコール数が一致しています。

print("ここに到達します")

実行すると次のように出力されます。

lua bracket_ok.lua
ここに到達します