Lua Style Guide



このスタイルガイドは、Roblox内のLuaコードを、可能な限り同一のスタイルと規約で統一することを目的としています。

このガイドは、GoogleのC++スタイルガイド を元に設計されています。Luaは非常に異なる言語ですが、このガイドの原則は依然として有効です。

指針

• スタイルガイドの目的は、議論を避けることにあります。

  • コードの整形方法に正解は一つではありませんが、一貫性が重要です。従って、このやや恣意的な基準を採用することで、コードを書く時間を増やし、フォーマットの詳細に関する議論の時間を削減します。

• コードは書くためではなく、読むために最適化してください。

  • コードは一度だけ書かれます。レビュー担当者や、後からコードに触れる他の開発者、さらには数ヶ月後の自分自身がこれを読む必要があります。

  • 差分がどのように見えるかを考慮し、一行をまたぐ変更がないようにすると、レビューが容易になります。

• 驚くような、または危険なLuaの機能（魔法的な機能）は避けてください。

  • 魔法のようなコードは便利ですが、問題が発生するとその理由や修正方法が不明瞭になります。

  • Metatables は、注意深く使用すべき強力な機能の一例です。

• 適切な場合、慣習的なLuaの書き方に一貫性を持たせてください。

ファイル構造

ファイルは（存在する場合）次の要素で構成されるべきです（順番通り）:

1. このファイルが存在する理由についての任意のブロックコメント（オプション）

   • ファイル名、作者、日付は含めない（これらはバージョン管理システムで確認可能）。

2. ファイルで使用されるサービス（GetService を使用）

3. モジュールのインポート（require を使用）

4. モジュールレベルの定数

5. モジュールレベルの変数と関数

6. モジュールが返すオブジェクト

7. return 文

リクワイア（require）の使用

一般

• すべての require 呼び出しはファイルの先頭で行い、依存関係を静的にしてください。

• require 文はモジュール名のアルファベット順に並べ替えてください。

リクワイアの構造

可読性を維持するため、require 文はブロックに分けることができます。これらのブロックはプロジェクトの内部構造を模倣し、以下の要素（存在する場合）で順序立てて構成されます:

1. 共通の祖先の定義

2. インポートされたすべてのパッケージのブロック

3. パッケージから派生した定義のブロック（サブフォルダごとに再帰可能）

4. 同一プロジェクト内からインポートされたモジュールのブロック（サブフォルダごとに再帰可能）

もし require 文をブロックに分ける場合:

• ブロックはまずグループ化に使用するサブフォルダ名、その後モジュール名のアルファベット順に並べ替えてください。

• 複数の require 文が共通のパスを共有する場合は、別のブロックにまとめることを推奨します。

ライブラリの読み込み

ライブラリとは、外部利用者向けにAPIを定義するプロジェクトで、通常は他のモジュールを require するためのトップレベルのテーブルを提供します。ライブラリは内部モジュールから構成される構造化された公開APIを提供し、内部の詳細が変更されても安定したインターフェースを維持できます。これにより、コードの共有だけでなく、自身のコード整理にも利用できます。

• ライブラリ内部では、公開モジュールおよび非公開モジュールを直接 require してください。例:

  -- MyLibrary/Foo.lua 内
  local MyLibrary = script.Parent
  local MyModule = require(MyLibrary.MyModule)

• ライブラリを利用する際は、まずAPI定義を読み込み、その後公開モジュールのパスを require してください。例:

  local ReplicatedStorage = game:GetService("ReplicatedStorage")
  local MyLibrary = require(ReplicatedStorage.MyLibrary)
  local MyModule = MyLibrary.MyModule

例

以下のようなプロジェクト構造の場合:

MyProject
|- FooBar
|   |- Foo.lua
|   |- Bar.lua
|- MyClass.lua
|- Packages
    |- Baz.lua
        |- Bazifyer.lua
        |- UnBazifyer.lua

MyClass は次のインポートブロックを定義するべきです:

-- 1. 共通の祖先の定義。
-- 相対パスを使用して、プロジェクトが複数の場所で動作するようにする。
local MyProject = script.Parent

-- 2. インポートされたすべてのパッケージのブロック。
-- Baz は依存しているライブラリなので、そのAPIを直接読み込みます。
local Baz = require(MyProject.Packages.Baz)

-- 3. パッケージから派生した定義のブロック。
-- APIを介してそのメンバーにアクセスします。ここでは単純なため、細かく分割する必要はありません。
local Bazifyer = Baz.Bazifyer
local UnBazifyer = Baz.UnBazifyer

-- 4. 同一プロジェクト内からインポートされたモジュールのブロック。
-- FooBar へのパスを個別に定義することで、記述が迅速かつ読みやすくなります。
local FooBar = MyProject.FooBar
local Foo = require(FooBar.Foo)
local Bar = require(FooBar.Bar)

メタテーブルの使用

メタテーブルは Lua の非常に強力な機能であり、演算子のオーバーロード、プロトタイプベースの継承、オブジェクトのライフサイクル管理に用いられます。 Roblox では、以下のような場合にメタテーブルの使用を推奨します:

• プロトタイプベースのクラスの実装

• タイプミスの防止

プロトタイプベースのクラス

クラスの定義方法はいくつかありますが、以下の方法を推奨します。これは Luau の型システムを活用するためです。強い型付けにより、クラスの使用方法が明確になり、型チェッカーや IDE が不整合を検出して警告を表示できます。

まず、通常の空のテーブルを作成します:

local MyClass = {}

次に、__index メンバーにクラス自身を設定します。これにより、インスタンスのメタテーブルとしてクラスのテーブルを利用できます。

MyClass.__index = MyClass

厳密な型推論を支援するため、クラスの形状を記述してください。これにより、クラスメンバーを2度指定する冗長性が生じますが、不整合があれば警告されます。

-- このモジュール外で使用する場合に型をエクスポートします
export type ClassType = typeof(setmetatable(
    {} :: {
        property: number,
    },
    MyClass
))

次に、クラスのデフォルトコンストラクタを作成し、上記の型定義を返り値（self）に割り当てます。

-- クラスのデフォルトコンストラクタは慣例として `new` と呼ばれます。
function MyClass.new(property: number): ClassType
    local self = {
        -- インスタンスのメンバーをここで定義します（初期値が nil でも構いません）。
        property = property,
    }
    -- 欠落しているフィールドについては MyClass.__index を参照するように Lua に指示します。
    setmetatable(self, MyClass)
    return self
end

インスタンスに作用するメソッドも定義できます。Luau の型解析機能導入前はコロン（:）を用いた定義が一般的でしたが、ここでは self の型を明示するためにドット（.）スタイルを使用します。これらのメソッドは、呼び出し時には通常通りコロンで呼び出すことができます。

function MyClass.addOne(self: ClassType)
    self.property += 1
end

これでクラスは使用する準備が整いました！ インスタンスを生成して動作を確認してみましょう:

local instance = MyClass.new(0)

-- インスタンスは単なるテーブルなので、プロパティは可視です:
print(tostring(instance.property)) -- "0"

-- メタテーブルによって、メソッドは MyClass から取得されます:
instance:addOne()
print(tostring(instance.property)) -- "1"

さらに、必要に応じて以下の追加が可能です:

• デバッグを容易にするために __tostring メタメソッドを導入する

• プライベートに近いメンバーを定義するため、接頭辞にアンダースコア2つを使用する

• インスタンスの型をチェックするメソッドを追加する:

  function MyClass.isMyClass(instance)
      return getmetatable(instance).__index == MyClass
  end

タイプミス防止

Lua では、存在しないキーにアクセスすると nil が返され、追跡が困難なエラーが発生する場合があります。 メタテーブルのもう一つの用途は、この問題を防ぐことです。列挙型のような性質を持つテーブルでは、以下のように __index メタメソッドでエラーを発生させることができます:

local MyEnum = {
    A = "A",
    B = "B",
    C = "C",
}

setmetatable(MyEnum, {
    __index = function(self, key)
        error(string.format("%q は MyEnum の有効なメンバーではありません", tostring(key)), 2)
    end,
})

__index はキーが存在しない場合にのみ呼び出されるため、MyEnum.A や MyEnum.B は通常通りの値を返しますが、MyEnum.FROB はエラーとなり、バグの特定が容易になります。

一般的な句読点

• セミコロン ; は使用しないでください。一行に複数の文を書く必要はありません。

一般的な空白と整形

• インデントにはタブを使用してください。

• タブ幅を4と仮定し、行の長さは100桁以内に保ってください。

• タブ文字は Luacheck で正確に解析されないため、StyLua の使用を推奨します。

• コメントはタブ幅4として80桁以内に折り返してください。コードとは異なり、短い行の方がコメントの可読性が向上します。

• 行末の余計な空白は残さないでください。（エディタの自動トリム機能を有効にしてください）

• ファイルの最後には必ず改行を入れてください。

• 垂直方向の整列（縦並びの整列）は避けてください。後の編集で乱れやすく、編集が困難になるためです。

良い例:

local frobulator = 132
local grog = 17

悪い例:

local frobulator = 132
local grog       =  17

• グループ間は単一の空行で区切ってください。ブロックの開始時に空行を入れるのは避けてください。余分な空行は全体の可読性を低下させます。

local Foo = require(Common.Foo)

local function gargle()
    -- gargle gargle
end

Foo.frobulate()
Foo.frobulate()

Foo.munge()

• 1行には1つの文を記述し、関数本体は新しい行に配置してください。

良い例:

table.sort(stuff, function(a, b)
    local sum = a + b
    return math.abs(sum) > 2
end)

悪い例:

table.sort(stuff, function(a, b) local sum = a + b return math.abs(sum) > 2 end)

• 複数の戻り値を返す関数では、関数が1行に収まっていない方がミスを見つけやすいです。

• if 文も、たとえ本体が return のみの場合でも、改行することで可読性が向上します。

良い例:

if valueIsInvalid then
    return
end

悪い例:

if valueIsInvalid then return end

このパターンは、入力や条件の検証の場合に特に有用で、複数行に分けることでログの追加や条件の拡張が容易になります。

• 演算子の前後にはスペースを入れてください（ただし、優先順位が明確な場合を除きます）。

良い例:

print(5 + 5 * 6^2)

悪い例:

print(5+5* 6 ^2)

• テーブルや関数呼び出しのカンマの後にはスペースを入れてください。

良い例:

local friends = {"bob", "amy", "joe"}
foo(5, 6, 7)

悪い例:

local friends = {"bob","amy" ,"joe"}
foo(5,6 ,7)

• 大きなインラインテーブルや関数呼び出しの場合、ブレースや関数を新たな行に配置すると可読性が向上します。

良い例:

foo(
    {
        type = "foo",
    },
    function(something)
        print("Hello,", something)
    end
)

悪い例:

foo({ type = "foo" }, function(something) print("Hello,", something) end)

長い式における改行

• 長い式は、論理的な単位ごとに改行してください。括弧内のサブ式も新しい行に分けると良いでしょう。

  • 改行する際は、行頭に演算子を配置して前行との連続性を示してください。

  • 必要であれば、一時変数を使用することを検討してください。

• 長い if 文の条件も、各条件を改行して記述してください。

良い例:

if
    someReallyLongCondition
    and someOtherReallyLongCondition
    and somethingElse
then
    doSomething()
    doSomethingElse()
end

悪い例:

if someReallyLongCondition and someOtherReallyLongCondition
    and somethingElse then
    doSomething()
    doSomethingElse()
end

• if 式での else 分岐も必ず記述し、改行して構造を明確にしてください。

良い例:

local scale = if someFlag() then 1 else 2

悪い例:

local scale = someFlag() and 1 or 2

• 条件が長い場合は、一時変数を用いて可読性を高めてください。

if-then-else 式について

• x and y or z のパターンよりも、if-then-else 式を用いる方が安全かつ高速で読みやすくなります。

良い例:

local scale = if someFlag() then 1 else 2

悪い例:

local scale = someFlag() and 1 or 2

• if 式には必ず else を付けてください。

• 複数行に渡る場合、then と else は新たな行に配置し、適切にインデントしてください。

良い例:

local scale = if someReallyLongFlagName() or someOtherReallyLongFlagName()
    then 1
    else 2

悪い例:

local scale = if someReallyLongFlagName() or someOtherReallyLongFlagName() then 1 else 2

ブロック

• if、while、repeat などの条件式では、括弧は不要です。

if CONDITION then
end

• 変数のスコープを限定するため、do ... end ブロックを使用してください。

local getId
do
    local lastId = 0
    getId = function()
        lastId = lastId + 1
        return lastId
    end
end

リテラル

• 文字列リテラルにはダブルクォーツを使用してください。

  • シングルクォーツを使用すると、アポストロフィのエスケープが必要になります。

  • 空文字列はダブルクォーツの方が認識しやすいです。

良い例:

print("Here's a message!")

悪い例:

print('Here\\'s a message!')

• 両方のクォーツを含む場合は、外側にダブルクォーツを使用するのが望ましいです。

テーブル

• 配列的なキーと連想配列的なキーが混在するテーブルは避けてください。混在すると、反復処理が困難になります。

• 配列的なテーブルは ipairs、連想配列的なテーブルは pairs を用いて反復してください。

• 複数行に渡るテーブルでは、末尾にカンマを追加すると、行の追加や並べ替えが容易になります。

良い例:

local frobs = {
    andrew = true,
    billy = true,
    caroline = true,
}

関数

• 関数の引数は可能な限り少なく（1つまたは2つ）してください。

• 関数呼び出し時は必ず括弧を使用してください。Luaでは括弧を省略できますが、可読性が低下します。

良い例:

local x = doSomething("home")
local y = doSomethingElse({u = 1, v = 2})

悪い例:

local x = doSomething "home"
local y = doSomethingElse {u = 1, v = 2}

• グローバル関数の定義は避け、関数はローカルで定義してください。

良い例:

local function add(a, b)
    return a + b
end

悪い例:

function add(a, b)
    return a + b
end

• テーブル内で関数を定義する際は、. と : の使い分けに注意してください。

良い例:

-- Frobulator.new() として呼び出す関数
function Frobulator.new()
    return {}
end

-- Frobulator:frob() として呼び出す関数
function Frobulator:frob()
    print("Frobbing", self)
end

悪い例:

function Frobulator.garb(self)
    print("Frobbing", self)
end

Frobulator.jarp = function()
    return {}
end

コメント

• インラインコメントは一行で記述し、複数行の場合は各行にコメント記号を入れてください。

• 関数やオブジェクトの意図を説明するためにブロックコメントを使用してください。

--[[
    宇宙の月光線を即座に遮断します。
    ミッドナイト（山岳標準時）15分以内にのみ呼び出すべきで、
    そうでない場合、宇宙の月光線が損傷する可能性があります。
]]--
local function stopCosmicMoonRay()
end

• コメントは「なぜ」そのようにコードが書かれているかに焦点を当て、「何を」しているかの説明だけに終始しないようにしてください。

  • 良い例:

  -- この条件が満たされないと、航空機のハンガーが水で満たされます。
  if waterLevelTooHigh() then
      drainHangar()
  end

  • 悪い例:

  -- 水位が高すぎるか確認する。
  if waterLevelTooHigh() then
      -- ハンガーを排水する。
      drainHangar()
  end

• セクション分けのためだけのコメントは避け、ファイル分割やモジュール化を検討してください。

命名規則

• 単語は省略せず完全に記述してください。略語は可読性を低下させる原因となります。

• クラスや列挙型のオブジェクトには PascalCase を使用してください。

• Roblox の API では PascalCase、ローカル変数、メンバー、関数には camelCase を使用してください。

• 定数には大文字のスネークケース（LOUD_SNAKE_CASE）を、プライベートメンバーには先頭にアンダースコアを付けてください（例: _camelCase）。

• ファイル名は、そのモジュールがエクスポートするオブジェクト名と一致させてください。たとえば、単一の関数 doSomething をエクスポートするモジュールなら、ファイル名は doSomething.lua とします。

-- FooThing.lua
local FOO_THRESHOLD = 6

local FooThing = {}

FooThing.someMemberConstant = 5

function FooThing.go()
    print("Foo Delta:", FooThing.someMemberConstant - FOO_THRESHOLD)
end

return FooThing

非同期処理と Yield

• yield する（非同期の）関数はメインタスク上で直接呼び出さないでください。coroutine.wrap や delay を使用し、Promise や類似の非同期プリミティブを利用することを検討してください。

  • 長所:

    • Roblox の非同期モデルにより、複雑な関数をコルーチンやその他の非同期手法を理解せずに利用できます。

  • 短所:

    • 意図しない yield により、データ競合が発生する可能性があります。

local value = 0

local function doSomething(callback)
    local newValue = value + 1
    callback(newValue)
    value = newValue
end

エラーハンドリング

• 失敗する可能性のある関数は、success, result を返すか、Result 型や非同期プリミティブを使用してください。

• 関数は、正しくない使い方の場合にのみエラーを投げるようにしてください。

local function thisCanFail(someValue)
    assert(typeof(someValue) == "string", "someValue は文字列でなければなりません！")

    if success() then
        return true, "おめでとうございます！勝利しました！"
    else
        return false, Error.new("ERR_BLAH", "重大なエラーが発生しました！")
    end
end

• 長所:

  • 例外を利用すると、未処理のエラーが自動的に呼び出し元へ伝播します。

  • スタックトレースが自動付加されます。

• 短所:

  • Lua は文字列しか例外として投げられないため、区別が難しいです。

  • 例外は関数の契約に明示されないため、呼び出し側でエラー処理を考慮する必要があります。

• 例外を投げる関数を呼び出す際には、pcall を使用し、期待されるエラーをコメントで明記してください。

一般的な Roblox のベストプラクティス

• すべてのサービスは、ファイルの先頭で game:GetService を用いて参照してください。

• モジュールをインポートする際は、まず API 定義を読み込み、その後パブリックモジュールを参照してください。