Go コードレビューチェックリスト

レビュー手順

コードレビューの出力をフォーマットする際は、assets/review-template.md を使用して、Must Fix / Should Fix / Nits の重大度分類で一貫した構造を確保してください。

1. gofmt -d . と go vet ./... を実行して機械的な問題をまず捕捉する
2. diff をファイルごとに読み込み、各ファイルについて以下のカテゴリを順番に確認する
3. 具体的な行番号とルール名で問題をフラグ付けする
4. すべてのファイルをレビューした後、フラグ付けした項目を再度読んで本当の問題であることを確認する
5. 重大度別（must-fix、should-fix、nit）にグループ分けして結果をまとめる

検証: レビュー完了後、diff を一度以上再度読み、フラグ付けした問題がすべて実在するものであることを確認します。具体的な行番号で正当化できない結果は削除します。

---

フォーマット

• gofmt: コードが gofmt または goimports でフォーマットされている → go-linting

---

ドキュメンテーション

• コメント文: コメントは説明対象の名前で始まり、ピリオドで終わる完全な文である → go-documentation
• Doc コメント: すべてのエクスポートされた名前に doc コメントがある。自明でないエクスポートされていない宣言にもある → go-documentation
• パッケージコメント: パッケージコメントは package 句に隣接し、空行がない → go-documentation
• 名前付き結果パラメータ: 意味を明確にする場合（例：同じ型の複数戻り値）のみ使用し、naked return を有効にするためだけに使用しない → go-documentation

---

エラー処理

• エラー処理: _ でエラーを無視しない。処理するか、返すか、または（例外的に）panic する → go-error-handling
• エラー文字列: 小文字で、句読点なし（固有名詞や頭字語で始まる場合を除く） → go-error-handling
• 帯域内エラー: マジックバリュー（-1、""、nil）を使用しない。複数返却とエラーまたは ok bool を使用する → go-error-handling
• エラーフロー制御: エラーを最初に処理して戻す。通常のパスを最小インデントに保つ → go-error-handling

---

命名規則

• MixedCaps: MixedCaps または mixedCaps を使用し、アンダースコアは使用しない。エクスポートされていない場合は maxLength であり MAX_LENGTH ではない → go-naming
• イニシャリズム: 一貫した大文字小文字を保つ：URL/url、ID/id、HTTP/http（例：ServeHTTP、xmlHTTPRequest） → go-naming
• 変数名: スコープが限定されている場合は短い名前（i、r、c）。スコープが広い場合は長い名前 → go-naming
• レシーバ名: 型の 1～2 文字の短縮形（Client の場合は c）。this、self、me は使用しない。メソッド間で一貫している → go-naming
• パッケージ名: スタッタリングなし（chubby.ChubbyFile ではなく chubby.File を使用）。util、common、misc を避ける → go-packages
• ビルトイン名を避ける: error、string、len、cap、append、copy、new、make をシャドーイングしない → go-declarations

---

並行処理

• ゴルーチンのライフタイム: ゴルーチンがいつ、かどうか終了するかが明確である。明白でない場合はドキュメント化する → go-concurrency
• 同期関数: 非同期より同期を優先する。呼び出し側が必要に応じて並行処理を追加できるようにする → go-concurrency
• Context: 第一パラメータ。構造体に含めない。カスタム Context 型を作成しない。必要ないと思っていても渡す → go-context

---

インターフェース

• インターフェースの位置: コンシューマパッケージで定義し、実装側では定義しない。プロデューサから具体的な型を返す → go-interfaces
• 時期尚早なインターフェース: 使用する前に定義しない。実装側でモッキング用に定義しない → go-interfaces
• レシーバ型: ミュテーション、同期フィールド、または大きい場合はポインタを使用する。小さい不変型の場合は値を使用する。混在させない → go-interfaces

---

データ構造

• 空のスライス: t := []string{} （非 nil ゼロ長）ではなく var t []string （nil）を優先する → go-data-structures
• コピー: ポインタ/スライスフィールド持つ構造体のコピーに注意する。*T メソッドのレシーバを値でコピーしない → go-data-structures

---

セキュリティ

• 暗号乱数: math/rand ではなく crypto/rand をキーに使用する → go-defensive
• Panic しない: 通常のエラー処理にはエラー戻り値を使用する。panic は本当に例外的な場合のみ使用する → go-defensive

---

宣言と初期化

• 類似するものをグループ化: 関連する var/const/type を括弧ブロックにグループ化。無関係なものは分離する → go-declarations
• var vs :=: 意図的なゼロ値には var を使用。明示的な代入には := を使用する → go-declarations
• スコープを削減: 宣言を使用場所の近くに移動する。if-init を使用して変数スコープを制限する → go-declarations
• 構造体初期化: 常にフィールド名を使用する。ゼロフィールドは省略する。ゼロ構造体は var を使用する → go-declarations
• any を使用: 新しいコードでは interface{} ではなく any を優先する → go-declarations

---

関数

• ファイル順序: 型 → コンストラクタ → エクスポートされたメソッド → エクスポートされていない → ユーティリティ → go-functions
• シグネチャフォーマット: ラップする場合、すべての引数を個別の行に配置し、末尾にカンマを付ける → go-functions
• Naked パラメータ: 曖昧な bool/int 引数には /* name */ コメントを追加するか、カスタム型を使用する → go-functions
• Printf 命名: フォーマット文字列を受け入れる関数は go vet のために f で終わる → go-functions

---

スタイル

• 行長: 厳密な制限はないが、不快なほど長い行を避ける。任意の長さではなく、セマンティクスで改行する → go-style-core
• Naked return: 短い関数のみ。中程度/大きい関数では明示的な return を使用する → go-style-core
• 値を渡す: バイト数を節約するためだけにポインタを使用しない。小さい固定サイズ型の場合は *string ではなく string を渡す → go-performance
• 文字列連結: シンプルな場合は +。フォーマットの場合は fmt.Sprintf。ループの場合は strings.Builder → go-performance

---

ログ

• slog を使用: 新しいコードは log や fmt.Println ではなく log/slog を使用する → go-logging
• 構造化フィールド: ログメッセージは fmt.Sprintf ではなく、キーバリューペア属性を含む静的文字列を使用する → go-logging
• 適切なレベル: Debug は開発者トレース用。Info は注目すべきイベント用。Warn は回復可能な問題用。Error は失敗用 → go-logging
• ログにシークレットを含めない: PII、認証情報、トークンはログに記録しない → go-logging

---

インポート

• インポートグループ: 標準ライブラリが最初、空行、外部パッケージ → go-packages
• インポートリネーム: 衝突がない限り避ける。衝突時にはローカル/プロジェクト固有のインポートをリネームする → go-packages
• インポート blank: import _ "pkg" は main パッケージまたはテストのみ → go-packages
• インポート dot: テストの循環依存ワークアラウンドのみ → go-packages

---

ジェネリクス

• 使用時機: 複数の型が同じロジックを共有し、インターフェースでは十分でない場合のみ → go-generics
• 型エイリアス: 新しい型には定義を使用。エイリアスはパッケージマイグレーション時のみ → go-generics

---

テスト

• 例: 実行可能な Example 関数またはテストで使用方法を説明する → go-documentation
• 有用なテスト失敗: メッセージは何が間違っていたか、入力、得られた値、期待値を含む。順序は got != want → go-testing
• TestMain: すべてのテストに共通セットアップ（テアダウン付き）が必要な場合のみ使用。まずスコープ付きヘルパーを優先する → go-testing
• 実際のトランスポート: HTTP モッキングより httptest.NewServer + 実際のクライアントを優先する → go-testing

---

自動化チェック

自動プレレビューチェックを実行します：

bash scripts/pre-review.sh ./...         # text output
bash scripts/pre-review.sh --json ./...  # structured JSON output

または手動で実行：gofmt -l <path> && go vet ./... && golangci-lint run ./...

進める前に、すべての問題を修正してください。リント設定については、go-linting を参照してください。

---

統合例

プロダクション HTTP サーバーを構築し、並行処理、エラー処理、context、ドキュメンテーション、命名規則を統合して検証したい場合は、references/WEB-SERVER.md を読んでください。

---

関連スキル

• スタイルの基礎: フォーマットについての議論を解決するか、clarity > simplicity > concision の優先度を適用する場合は go-style-core を参照してください
• リント設定: golangci-lint を設定するか、CI に自動チェックを追加する場合は go-linting を参照してください
• エラー戦略: エラーラップ、sentinel エラー、handle-once パターンをレビューする場合は go-error-handling を参照してください
• 命名規則: 識別子名、レシーバ名、またはパッケージシンボルのスタッタリングを評価する場合は go-naming を参照してください
• テストパターン: テストコード、table-driven 構造、失敗メッセージ、またはヘルパー使用をレビューする場合は go-testing を参照してください
• 並行処理安全性: ゴルーチンのライフタイム、チャネル使用、またはミューテックス配置をレビューする場合は go-concurrency を参照してください
• ログプラクティス: ログの使用、構造化ログ、または slog 設定をレビューする場合は go-logging を参照してください