ruins-code

name	ruins-code
description	ruins のコード規約。doc.go・コメント・ゲッター/コンストラクタ・YAGNI・公開API・lint・テストの書き方。Goコードを書く/直すときに使う

ruins コード規約

Go のベテランとして、シンプルさとテストしやすさを最優先する。責務によって package を分け、Go のベストプラクティスに従う。

パッケージ

• 各 package の doc.go に記載する: package の説明 / 使い分け / 責務 / 仕様。
• 責務によって適切に package を分ける。

コメント

• ロジックやコメントは日本語で書く。
• 注意が必要な箇所だけを最小限コメントする。見ればわかる自明なコメントは書かない。
• コメントに体言止めを使わない（意味が不明瞭になるため）。
• コメントのカッコでの補足は最小限にし、完全な文章で説明する。

設計・API

• 不要なゲッター/セッター関数は定義しない。
• コンストラクタは1つの型につき最大1つ。必要ならオプションパターンで定義する。
• YAGNI 原則に従い、使わないうちから実装しない。ただし余地のある設計はしておく。
• 定義する関数は最小限に保つ。呼び出されていない関数は削除する。
• 公開 API を最小限にする。private と public を明確に区別する。
• linter ルールは無視設定しない。
• 生成ファイル（*_gen.go）は手編集しない。生成元を直して再生成する。

テスト

• 極力 github.com/stretchr/testify のアサート（assert.Error / require.Error 等）を使う。t.Error() / t.Fatal() は使わない。
• テストしやすく設計し、テストを追加する。
• 実行は make test（Ebiten のウィンドウが出るのを防ぐため）。
• テスト名は Test<対象関数名>_<日本語で検証内容> にし、名前だけで何を検証するか分かるようにする。例 func TestNewItemSpec_本のスキル未指定はエラー(t *testing.T)。table-driven の場合は関数名を Test<対象関数名> とし、各ケースを t.Run("<日本語で検証内容>", ...) で表す。
• アサートは検証対象の種類で選び、過不足のない厳密さにする。require.Error だけの、内容を見ない自明なエラーテストにはしない。
  • 値すなわち戻り値や計算結果は assert.Equal で全文一致させる。自分が生成する確定値ほど、厳密一致が回帰を捕まえる。
  • エラーはまず errors.Is / errors.As で同定する。センチネルや型があれば文言に依存せず、正しい種類の失敗かを厳密に確認できる。
  • 文字列一致がやむを得ないエラーは assert.ErrorContains で安定した意味のある断片だけを見る。エラー全文は下位層・OS・標準ライブラリの文言やパス・IDが混ざって脆いので、全文一致させない。
  • assert.Contains はコレクションの包含判定にだけ使う。文字列の部分一致を全文一致の代わりに使わない。

検証

• コード変更後は make check を実行して壊していないか検証する。