golang-code-style

Go のコードを書くとき、見直すとき、チームの書き方の決まりを作るときに効きます。samber が公開する、Go 専用のスキル集の 1 本です。

本文は冒頭で、整形は整形の道具に任せ、このスキルは「分かりやすさ」を受け持つ、と線を引いています。「賢いより分かりやすいほうがよい」という Go の格言を軸に、人の判断が要る書き方を決めていきます。*.go のファイルを扱うときに読み込まれる設定です。

これを超える行は折る目安

120 字

関数の引数の上限の目安

4 つ

同梱の試験の課題

24 個

同梱ファイル（2026-10-23 時点）

2 件

決まりの並び

• 行の長さと折り方約 120 字を超えたら、意味の切れ目で折る。引数が 4 つ以上の呼び出しは 1 行に 1 つ
• 変数の宣言ゼロの値から始めるなら var、値を入れるなら :=。スライスとマップは nil にしない
• 流れの書き方誤りと端の場合を先に返す。return の後の else は消す。同じ変数の比較は switch
• 関数の作り短く 1 つの仕事。引数は 4 つまで。context.Context を最初に
• 値か参照か小さい型は値で渡す。書き換える・大きい（約 128 バイト以上）・nil に意味があるときだけ参照
• ファイルの中の並び型・作る関数・方法をまとめる。外に出す名前は少なく

そのほか、文字列の扱い（簡単な変換は strconv、複雑な組み立ては fmt.Sprintf、繰り返しの中では strings.Builder）、型の変換（any より型引数）、考え方（少しの写しは少しの依存よりよい、reflect を避ける、早すぎる抽象化をしない）の節があります。

書き方で意図を見せる

変数の宣言の決まりは、形が意図を伝える、という考え方です。var count int は「ゼロから始まる」、name := "default" は「値を入れて始める」と読めるように使い分けます。

構造体を値から作るときは、必ず項目の名前を書きます。名前を書かない並べ方は、型に項目が足されたり並びが変わったりすると壊れるからです。

早めに返し、else を消す

誤りと端の場合を先に処理して返し、本来の流れは浅い字下げに置きます。if の中身が return や break で終わるなら、else は書きません。

代入の分かれ道は、まず既定の値を入れ、条件ごとに上書きする形にします。else if を重ねる書き方は、既定の値があることを隠す、というのが本文の理由です。

条件が 3 つを超えたら名前を付ける

if の条件に 3 つ以上の項があるなら、isAdmin・isOwner のような名前の付いた真偽の値に取り出します。ただし、重い確かめは条件の中に残します。前の条件で決まれば評価を飛ばせる、という利点を残すためで、同梱の文書に良い例と無駄な例が並んでいます。

大きなコードを見直すとき

コード全体の書き方を見直すときは、最大 5 つの下位のエージェントを並べ、流れの書き方・関数の作り・変数の宣言・文字列の扱い・ファイルの中の並びのように、互いに独立した観点ごとに調べさせて結果をまとめます。Claude Code では ultracode で複数のエージェントの進め方を明示的に選ぶよう、本文は書いています。

名前の付け方、整形の道具の設定、文書の注釈

frontmatter の説明は、名前の付け方は golang-naming、整形の道具の設定は golang-lint、文書の注釈は golang-documentation の担当で、このスキルの範囲ではない、と書いています。本文は、受け手の型を値にするか参照にするか（golang-structs-interfaces）、選択肢の構造体などの設計の型（golang-design-patterns）も別に回しています。

決まりを多くの呼び出し元へ一度に当てたいとき

見直しで見つかった違反を、たくさんの呼び出し元にまとめて当てるのは golang-refactoring の担当です。外に出す名前を内側に戻すときは、呼び出し元を一度に書き換え、interface を満たさなくなる変更は止める golang-gopls の名前の変更を使え、と本文にあります。

会社の決まりがすでにあるとき

本文は、自分を「共同体の既定」と位置づけ、明示的に置き換える会社のスキルがあればそちらを優先する、と書いています。誤りの扱いは golang-error-handling、テストの書き方は golang-testing が、同じスキル集で受け持ちます。

書かれているコマンドと道具

frontmatter の allowed-tools には、Read・Edit・Write・Glob・Grep、Bash(go:*)・Bash(golangci-lint:*)・Bash(git:*)、下位のエージェント（Agent）が並びます。allowed-tools は道具を絞る設定ではなく、呼ばれた回に確認なしで使ってよい道具を宣言するものです。ほかの道具も使えます。

前提として要る実行ファイルは go だけです。本文と同梱の文書には、外へ通信する手順はありません。

頼んだ書き方より、決まりを優先する

決まりを外したいときは、コードに注釈を残せ、と本文は書いています。チームの決まりと違う場面が多いなら、会社のスキルで置き換えるほうが手早いです。

スライスを nil にしない決まりは、Go の公式の手引きと逆

このスキルは、スライスとマップは必ず初期化し、nil のままにしない、としています。nil のマップは書き込みで panic になり、nil のスライスは JSON で null になって、API を使う側を驚かせる、という理由です。

一方、Go の公式の Wiki の CodeReviewComments（2026-10-23 確認）は、空のスライスの宣言は var t []string の nil を好む、と書いています。ただし同じ手引きも、JSON で [] にしたいときは nil でない空のスライスがよい、という例外を挙げています。チームでどちらに揃えるかを先に決めておくと、見直しで揉めません。

先回りの確保はしない

容量が分かっているときは make([]User, 0, len(ids)) のように先に確保します。ただし、よくある場合が 10 件なのに make([]T, 0, 1000) と見込みで大きく取るのは、無駄だとしています。

例の一部は公開元の作ったライブラリを使う

考え方の節は、標準の slices と maps を使い、絞り込み・まとめ・切り分けには github.com/samber/lo を使え、としています。samber/lo は、このスキル集の公開元と同じ samber のライブラリで、外部の依存として取り込むことになります。同じ節にある「少しの写しは少しの依存よりよい」という格言と合わせて、依存を増やすかどうかはチームで判断してください。

整形の道具が受け持つもの

多くの決まりは、gofmt・gofumpt・goimports・gocritic・revive・wsl_v5 の 6 つの道具で自動で当てられる、と本文は書いています。設定は golang-lint の担当です。

1 行は何文字までですか

決まった上限はありません。約 120 字を超える行は折るべき（MUST）とされ、折る場所は字数ではなく意味の切れ目です。関数の宣言が長すぎるなら、折り方より引数を減らすのが本当の直し方だ、と本文は書いています。

引数が多い関数はどうしますか

引数は 4 つまでが目安で、それを超えたら選択肢の構造体にまとめます。並びは context.Context が最初、次に入力、最後に結果の書き込み先です。選択肢の構造体の作り方は golang-design-patterns に回されています。

値で渡すか参照で渡すか、迷ったら

string・int・bool・time.Time のような小さい型は値で渡します。参照にするのは、関数が中身を書き換える、構造体が大きい（約 128 バイト以上）、nil に意味がある、の 3 つの場合です。同梱の文書は、小さな構造体を読むだけなら値のほうが速いことが多く、迷ったら測れ、と書いています。

同梱ファイルには何がありますか

references/details.md に、条件に名前を付ける例と、値か参照かの詳しい説明があります。もう 1 つは evals/evals.json で、ゼロの値の宣言、nil にしないスライス、早めに返す書き方、引数の数など、書き方を試す 24 の課題が入っています（2026-10-23 時点）。