zig-best-practices

Zig のベストプラクティス

CLAUDE.md の型優先、関数型、エラー処理のパターンに従っています。このスキルでは、Zig 固有のイディオムのみを扱います。

型システムのパターン

相互に排他的な状態にはタグ付きユニオンを使用します — 複数の nullable フィールドを持つ構造体で可能になってしまう無効な組み合わせを防ぎます。

const RequestState = union(enum) {
    idle,
    loading,
    success: []const u8,
    failure: anyerror,
};

エラーセットを明示します — 何が失敗する可能性があるかを正確に示します。anyerror は失敗の種類を隠してしまいます。

const ParseError = error{ InvalidSyntax, UnexpectedToken, EndOfInput };
fn parse(input: []const u8) ParseError!Ast { ... }

ドメイン ID には個別の型を使用します — コンパイラーが異なる ID 型の取り違えを防ぎます。

const UserId = enum(u64) { _ };
const OrderId = enum(u64) { _ };

comptime による検証 — 無効な設定を実行時ではなくコンパイル時に検出します。

fn Buffer(comptime size: usize) type {
    if (size == 0) @compileError("buffer size must be greater than 0");
    return struct { data: [size]u8 = undefined, len: usize = 0 };
}

メモリ管理

• 割り当てを行うすべての関数にアロケーターを明示的に渡します。グローバルなアロケーター状態は使用しません。
• リソースを取得した直後に defer resource.deinit() を置きます。これにより、クリーンアップ処理を作成処理の近くに記述できます。
• エラーパスでのクリーンアップには errdefer を使用し、無条件のクリーンアップには defer を使用します。
• 一括処理や一時的な処理にはアリーナアロケーターを使用します。すべてを一度に解放できます。
• テストでは std.testing.allocator を使用します。スタックトレース付きでリークが報告されます。

fn createResource(allocator: std.mem.Allocator) !*Resource {
    const resource = try allocator.create(Resource);
    errdefer allocator.destroy(resource);  // runs only on error
    resource.* = try initializeResource();
    return resource;
}

主な規約

• var より const を、raw ポインターよりスライスを優先します。
• anytype より comptime T: type を優先します。明示的な型を使うと、より分かりやすいエラーが得られます。anytype は、コールバックや std.debug.print のような、実際に多相性が必要な場合にのみ使用します。
• switch は網羅的に記述します。else を含め、エラーを返すか、真に起こり得ないケースには unreachable を使用します。
• 名前空間付きのログには std.log.scoped(.module_name) を使用し、モジュールレベルで const log 定数を定義します。
• 大きくまとまったファイルは慣用的なスタイルです。テストを実装と並べて記述し、comptime ジェネリクスをファイルスコープに置きます。

高度なトピック

• ジェネリックコンテナー（キュー、スタック、ツリー）：GENERICS.md を参照してください。
• C ライブラリとの相互運用（raylib、SDL、curl）：C-INTEROP.md を参照してください。
• メモリーリークのデバッグ（GPA、スタックトレース）：DEBUGGING.md を参照してください。

ツール

zigdoc — 標準ライブラリや依存関係のドキュメントを参照します。

zigdoc std.mem.Allocator   # std lib symbol
zigdoc vaxis.Window        # project dependency
zigdoc @init               # create AGENTS.md with API patterns

ziglint — .ziglint.zon の設定による静的解析を行います。

ziglint                    # lint current directory
ziglint --ignore Z001      # suppress specific rule

参考資料

• 言語リファレンス：https://ziglang.org/documentation/0.15.2/
• 標準ライブラリ：https://ziglang.org/documentation/0.15.2/std/
• Zig ガイド：https://zig.guide/