Zenn
👻

変数シャドーイングで大混乱！？意図しないバグを防ぐための実践ガイド

2025/01/09に公開
Go
tech

はじめに

Go言語では := を使った短い変数宣言を頻繁に活用します。しかし、このシンプルかつ便利な機能が、思いもよらぬバグの温床となることがあります。
特にやっかいなのが 変数シャドーイング です。上位スコープに定義された変数と同じ名前で新たに変数を宣言すると、意図せず 元の変数が“隠れ” てしまう現象が起こります。
この記事では、Go言語で起きがちな変数シャドーイングの実例や、それによって引き起こされる意図しない動作を紹介し、回避策を探っていきます。

1. Goにおける変数シャドーイングとは

変数シャドーイングを理解するための前提：Goのスコープ

静的スコープ（Static Scope）

Go言語では、変数の有効範囲（スコープ）は コード上での宣言位置 によって決まります。一般的には以下のスコープが存在します。

  • パッケージスコープ
    パッケージ全体で参照できる変数や関数など。package 宣言の直下で宣言された名前は、同一パッケージ内から参照できる。

  • ファイルスコープ
    Goの場合は、同一パッケージ内ならファイルが分かれていても大体同じスコープとして扱われます。ただし、ファイル単位のスコープが出てくることは比較的少なく、mainパッケージなど大きく分けられる場合がある程度です。

  • 関数スコープ
    関数内で宣言された変数は、その関数の中のみで有効です。

  • ブロックスコープ
    {} で囲まれたブロック内で宣言された変数は、ブロック内のみ有効です。if 文や for 文などもブロックを形成し、ここで宣言された変数はブロックを抜けると参照できません。

変数シャドーイングは、上位スコープ（パッケージ、関数、ブロックなど）で宣言されている同名の変数を、下位のブロックスコープなどで再度宣言してしまうことで起こります。

短い変数宣言（:=）がシャドーイングを引き起こす主な要因

Goでは、以下のように 短い変数宣言 を使う機会が非常に多いです。

x := 10

これは、

var x = 10

と同様に変数 x を宣言・初期化する文法ですが、次のような特徴があります。

  1. 新規変数の宣言 ＋ 初期化 を同時に行える
  2. 同じスコープで既に宣言済みの変数に対して := を使うとコンパイルエラーになる場合がある
  3. ただし、複数の変数を同時に宣言する際に、1つでも新規変数があれば全体が再宣言扱いとなる
    • 例：x, err := someFunc() という書き方では、すでに err が宣言されている上位スコープがあったとしても、もし x が新規変数であれば問題なくコンパイルが通り、結果的に err がシャドーされてしまう

短い変数宣言は便利ですが、 「新規の変数を宣言したつもりがないのに、実は内部で別の変数が宣言されていた」 というケースが少なくありません。これがシャドーイングの主な原因となります。

シャドーイングによる典型的な挙動例

以下の例を見てみましょう。

package main

import "fmt"

func main() {
    x := 10
    if true {
        x := x + 20
        fmt.Println("Inside if:", x) // 30 になる
    }
    fmt.Println("Outside if:", x)    // 10 のまま
}
  • main 関数冒頭で x := 10 が宣言されています。(外側スコープ)
  • if true { ... } ブロックの中で x := x + 20 と書いているため、Goは 「新しい x の宣言」 と見なします。(内側スコープ)
  • 結果として、ブロック内の x は「外側の x を使って算術計算した値（30）」で初期化されますが、これは 外側の x とは別物 です。
  • したがって、ブロックを抜けると内側の x は破棄され、外側の x は相変わらず 10 のまま。Outside if: で出力すると 10 が表示される、という仕組みです。
    このように、 同名変数を内側ブロックで短い変数宣言を使って書くと、その上位スコープの変数とは別のものになり、上位スコープの変数が“隠される” （＝シャドーイング）状況が発生します。

上位スコープと下位スコープの境目に注意

Goでは、 新しいブロック が始まるたびにスコープが作られます。

if condition {
    // ブロックA
} else {
    // ブロックB
}
for i := 0; i < 10; i++ {
    // ブロックC
}

それぞれのブロック内で := を使うと、同名変数のシャドーイングが発生しやすくなります。特に以下のような状況では注意が必要です。

  1. 複数のブロックで同じ名前の変数を使いたいとき
    • 例：if/else 両方で x := ... と書いてしまうなど
  2. 関数の中で、さらに無名関数やゴルーチンを定義しているとき
    • go func() { ... }() の中で同名変数を := で宣言してしまうと、思わぬスコープで違う変数を扱うことがある
  3. エラー変数 err の再宣言
    • Goコードでは頻繁に err を使うため、関数内の上位スコープですでに err が宣言されているにもかかわらず、別の箇所で err := xxx と書いてしまい、デバッグを困難にする例がよく見られる

シャドーイング自体はGo言語の仕様でありコンパイルエラーではない

Goコンパイラは、「 一度宣言された名前を再び宣言している 」 だけであれば、それ自体はエラーとしません。ただし、 同一スコープ内でまったく同じ名前を再宣言 した場合はコンパイルエラーになります。

  • 同一スコープでの再宣言
func main() {
    x := 10
    x := 20 // コンパイルエラー
}

「同じスコープ内」で同じ変数名を := するためにエラーとなる

  • 別スコープでの再宣言（シャドーイング）
func main() {
    x := 10
    {
        x := 20 // コンパイルエラーにならない（新しいスコープ）
    }
}

「新しいスコープ」で同じ変数名を := しているため、有効なコードだがシャドーイングが発生

このように、Goの仕様としては「内側のブロックは外側のスコープに属していないため、再宣言してもOK」という考え方です。エラーにはならない代わりに、意図しない動作を招きやすい という怖さを持ち合わせています。

まとめ

  • 変数シャドーイングはGo言語のスコープと短い変数宣言（:=）の組み合わせによってよく起きる事象。
  • 上位スコープの変数を「更新するつもり」だったのに、実は「新しい変数を宣言」していた、というのが典型的な落とし穴。
  • Goの仕様としてはコンパイルエラーにならないため、開発者側で十分に気をつける必要がある。
  • 特にエラー変数 err などはシャドーイングしがちなので、注意深くコードレビュー＆リントツールを使って検出・防止するのがおすすめ。

これらのポイントを押さえておくと、Go言語でのシャドーイングを引き起こしやすいパターンや対処法を自然に理解し、よりバグを減らすコーディングができるようになるでしょう。

2. 実際のコード例：短い変数宣言の落とし穴

典型例：if ブロック内でのシャドーイング

コード例

package main

import "fmt"

func main() {
    x := 10
    if true {
        x := x + 20
        fmt.Println("Inside if:", x) // 30 になる
    }
    fmt.Println("Outside if:", x)    // 10 のまま
}

解説

  1. 外側スコープでの宣言
    • main 関数内の最初の行で x := 10 と宣言。これが外側スコープの x です。
  2. 内側スコープ（if ブロック）での再宣言
    • if true { x := x + 20 } は、「外側の x を読み込んで 20 を足し、その結果を 新たな x として宣言 する」ことを意味しています。
    • これにより、if ブロック内では「30 という値を持つ新しい x」が生成され、外側の x は隠されています。
  3. ブロックを抜けると内側の x は消滅
    • Inside if: の出力は 30 ですが、ブロックを出た瞬間に内側の x はスコープ外となり、外側の x（値が 10）が有効に戻ります。
    • そのため、Outside if: の出力は 10 のままです。

ポイント

  • 外側スコープの変数を“更新”したつもり が、実際には 別の変数を新規に宣言 している。
  • 使い捨てのブロック内変数ならまだしも、外側変数を意図的に書き換えたい場合には重大なバグの原因となる。

複数変数を一度に宣言する場合のシャドーイング

Go言語では、短い変数宣言（:=）を使って、下記のように 複数の変数を同時に宣言・代入 することがよくあります。

コード例

package main

import (
    "fmt"
    "errors"
)

func main() {
    var err error
    x := 0

    // 何かの処理（エラーが起きる可能性あり）
    // ...
    err = errors.New("Some error occurred")

    // ここで本当は x のみ新規初期化するつもりだった
    x, err := someFunc() // ここで短い変数宣言を使ってしまう

    if err != nil {
        fmt.Println("Error:", err)
        return
    }

    fmt.Println("Value of x:", x)
}

func someFunc() (int, error) {
    return 42, nil
}

解説

  1. 上位スコープでの変数宣言
    • 関数 main の先頭にて、 var err error と x := 0 が既に宣言されています。
  2. x, err := someFunc() の挙動
    • ここでは、x はすでに宣言済みなのに「再度宣言」され、しかも err 変数も同時に“再宣言”される可能性があります。（Goの仕様では「同じスコープ内に存在しない変数」が一つでもあれば、この書き方はコンパイルが通ってしまう）
  3. 結果的に発生する問題
    • 元々の err が上位スコープにあったにもかかわらず、ここで内側スコープの新しい err が作られる（＝シャドーイング）。
    • バグが混入すると、元々持っていたエラー情報（Some error occurred）を意図せず上書きしてしまったり、別の箇所で err を確認した時に 想定と違う値を持っている ことがある。
  4. 意図しないバグが生まれる例
    • テストコードや他の関数で「この err が正しくハンドリングされているか」をチェックしているつもりが、実は内側スコープの err を見に行ってしまい、ロジックが破綻するケース。

ポイント

  • 「更新しようと思っただけなのに、宣言と初期化を同時にやっていた」 という混乱が発生する。
  • Goは複数変数の同時初期化に := を使うことが多いため、意図せずシャドーイングが起こりやすい。

for ループ内でのシャドーイング

for 文の中でも、意図しない短い変数宣言によるシャドーイングがよく起こります。

コード例

func processItems(items []int) {
    result := 0
    for i := 0; i < len(items); i++ {
        // 本当は外側で宣言した 'result' を使って加算していきたい
        result := result + items[i]
        fmt.Println("inner Result:", result)
    }
    fmt.Println("Final Result:", result)
}

解説

  1. 外側スコープの result
    • func processItems(items []int) の先頭で、result := 0 を宣言しています。これは関数スコープで有効な変数です。
  2. for 文のブロック内での再宣言
    • result := result + items[i] は、短い宣言（:=）を用いて 「新しい result を生成」 しています。
    • しかもこの result はブロックスコープ内で有効なため、ループブロックを抜けると元々の result には全く反映されません。
  3. 期待する動作との乖離
    • 開発者の意図：「ループで要素を足し込んで result を更新し続けたい」
    • 実際の動作：「ループ内で新しい result を宣言 → そのループブロック終了と共に消滅 → 外側の result は更新されずに 0 のまま」
    • 結果、「Final Result: 0」となる。
  4. 修正案
    • ループ内では再宣言ではなく、 単純に代入（=） を使う。
result = result + items[i]

* これで外側の `result` を正しく更新できるようになる。

ポイント

  • ループカウンタや集計用変数など、 ループ外部で宣言しておくべきものを、うっかり := で再宣言してしまう と、期待と異なる動作をしてしまう。
  • ループ終了後に「なぜ更新されていないのか...？」と混乱する典型例。

まとめ

  • 短い変数宣言（:=）はGoの特徴的で便利な機能 である一方、非常に簡単に「変数シャドーイング」を引き起こしてしまう。
  • ブロックスコープや複数変数の同時宣言、ループ内 などが、シャドーイングの「ホットスポット」。
  • 宣言と初期化を同時に行う書き方は手軽ですが、「本当に更新だけしたいのか、それとも新しい変数を作りたいのか」を常に意識することが重要。

意図しないシャドーイングはデバッグを難しくし、プロダクションコードにバグを潜ませやすいものです。 小さなコード修正やリファクタリングの際にも、 := の使いどころに細心の注意を払い、コードレビューやリントツールの活用によって発覚しやすくしておきましょう。

3. 現場で起きがちなトラブル事例

エラー変数（err）のシャドーイングによる不具合

シナリオ

  • 関数内で頻繁にエラー変数 err を使う Goの慣習。
  • 新しい機能追加やリファクタリング時、あるブロック内で err := someOperation() と書いてしまい、上位スコープの err をシャドーイング。
  • 本来拾うはずだったエラーが別のスコープで「無かったことに」なってしまい、実際にはエラーが起きているのに、ハンドリングがスルーされる。

具体例

func processOrder(orderID int) error {
    var err error
    // すでに上位スコープで 'err' 宣言済み

    userID, err := fetchUserID(orderID) // ここも 'err'
    if err != nil {
        return fmt.Errorf("failed to fetch user: %w", err)
    }

    // ... いろいろな処理 ...

    if someCondition {
        userID, err := anotherUserFunc(orderID) 
        // ↑ ここで 'err' を再度シャドーイング
        // 実際には上位スコープの 'err' とは別物
        if err != nil {
            // ここでの err ハンドリングは
            // "内側スコープの err" に限定される
        }
    }

    // someCondition が true で失敗しても、
    // 内側スコープの err は外へ出ないので
    // 以降の処理には影響しない → バグの温床
    return nil
}

影響

  • テストコードでは「一部の条件」でしか発生しないエラーを見落としやすい。
  • プロダクション環境で思わぬ不具合として顕在化し、ユーザに不正な処理結果を返してしまう危険もある。

解消ポイント

  • 複数のスコープで同じ変数名（特に err）を安易に使わない。
  • 「更新だけなら := ではなく = を用いる」「あえて変数名を変える（例：userErr）」「スコープを分離しすぎない」など、シャドーイングが起きにくい書き方を心がける。

短い変数宣言による意図しない「更新漏れ」

シナリオ

  • 一度初期化した変数を、内部で少しずつ更新していきたいケース。
  • しかしブロック内で := を使ってしまい、「外側の変数を更新するつもりが、内側で新たに宣言しただけで終わっている」という状況に陥る。

具体例

func sumAndPrint(arr []int) {
    total := 0
    for _, val := range arr {
        // 本来は `total` を増やしたい
        total := total + val // シャドーイング発生
        // ↑ ここでできた total は for ブロック内だけ有効
        // 外側の total は更新されていない
		fmt.Println("inner Total:", total)
    }
    fmt.Println("Total:", total) 
    // 結果は 0 のまま → 想定外のバグ
}

影響

  • 計算ロジックの誤動作。数値だけでなく、文字列や構造体を扱う処理でも同様に「更新漏れ」が起こりうる。
  • 大規模開発で忙しくレビューが追いつかないと、この手のバグは気づきづらい。

解消ポイント

  • 「再宣言が必要なのか、単に代入するだけで良いのか」を、Go特有の := 構文を使うたびにチェックする。
  • ループで使う変数はループの外側で明示的に var total int などを宣言し、ブロック内では = を使う運用を徹底。

複数の変数を一度に初期化する処理での混乱

シナリオ

  • Goでよく見かける x, err := someFunc() のように、複数の変数を同時に短い宣言で初期化する書き方。
  • すでにスコープ内に同じ名前の変数（特に err）が存在するにも関わらず、x が新規変数として登場しているためコンパイルは通り、実行すると上位スコープの err がシャドーイングされる。

具体例

func handleRequest() {
    var err error
    code := 0

    // 既に 'err' は上位スコープで宣言済み
    code, err := doSomething() 
    // 'code' は新規、 'err' は上書きされる可能性大

    if err != nil {
        // 期待通りエラーを判定しているつもり
        // 実はシャドーイングかもしれない...？
        // もしこのブロック外でも 'err' を参照している箇所があると混乱しやすい
    }

    // 他の処理 ...
}

影響

  • コードを読む人が「どのスコープの err が参照されているのか」をすぐに理解しづらい。
  • 小規模プロジェクトだと一見シンプルに見えても、大規模プロジェクトや複数人での開発では極めて紛らわしいトラブル要因になる。

解消ポイント

  • 「複数の変数をまとめて短い宣言を行う」書き方は便利だが、上位スコープで既に宣言済みの名前を含んでいないか注意する。
  • リントツール（例：golangci-lint）の shadow チェッカーなどを使えば、この種のシャドーイングを自動検知できる。

テストで再現しないが本番で問題が発生するケース

シナリオ

  • テストコードは規模が小さい or 想定パスしか通していないため、シャドーイングによる挙動不良が表面化しない。
  • 本番環境で大量のデータや特殊な入力が来たときにだけ、シャドーイングされた変数を参照している箇所でバグが起きる。
  • 「テストも全部通ったのに、なぜ本番で…？」という最も厄介なタイプの不具合。

具体例

main.go

func processData(data []string) {
    result := []string{}
    for _, d := range data {
        if len(d) > 10 {
            // テストではこの条件を通る文字列がない
            // 本番データではここに入り込む
            result := append(result, d[:10]) 
            // ↑ ここで 'result' が新規宣言され、外側を更新しない
        } else {
            result = append(result, d)
        }
    }
    // 実際にはシャドーイングのせいで一部データが正しく追加されていない
    // テストだと全データが10文字以下なので見落とす
}

main_test.go

package main

import "testing"

func Test_processData(t *testing.T) {
	type testCase struct {
		name string
		data []string
		want []string
	}

	tests := []testCase{
		{
			name: "要素数10個未満",
			data: []string{"12345", "1234", "123", "12", "1"},
			want: []string{"12345", "1234", "123", "12", "1"},
		},
		{
			name: "要素数10個",
			data: []string{"1234567890", "123456789", "12345678", "1234567", "123456", "12345", "1234", "123", "12", "1"},
			want: []string{"1234567890", "123456789", "12345678", "1234567", "123456", "12345", "1234", "123", "12", "1"},
		},
        // 何らかの理由で下記のテストを忘れてしまっている
		// {
		// 	name: "要素数10個より多い",
		// 	data: []string{"1234567890a", "1234567890", "123456789", "12345678", "1234567", "123456", "12345", "1234", "123", "12", "1"},
		// 	want: []string{"1234567890a", "1234567890", "123456789", "12345678", "1234567", "123456", "12345", "1234", "123", "12", "1"},
		// },
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			got := processData(tt.data)
			if len(got) != len(tt.want) {
				t.Errorf("want %v, got %v", tt.want, got)
			}
			for i := 0; i < len(got); i++ {
				if got[i] != tt.want[i] {
					t.Errorf("want %v, got %v", tt.want, got)
				}
			}
		})
	}
}

影響

  • 「特定条件下だけ結果がおかしい」「なぜか本番でだけ空っぽになる」といった状況が起きる。
  • 原因を特定しづらく、バグ修正に時間を要する。

解消ポイント

  • テストコードで多様なパターン（境界値・最大値・例外パス）をカバーし、実際に想定されうる条件を網羅する。
  • リファクタリングや新機能追加の際、「スコープの再宣言が起きていないか」をチーム内でレビューするフローを導入。

無名関数・ゴルーチン内での変数名の衝突

シナリオ

  • Goでは無名関数やゴルーチンを使った並行処理が容易。
  • しかし、無名関数の中で外側と同じ名前の変数を := で宣言すると、その無名関数内だけ別の変数を扱ってしまい、並行処理の動作が想定とズレることがある。

具体例

package main

import (
	"fmt"
	"time"
)

func main() {
	msg := "Hello"
	go func() {
		msg := msg + " World"
		fmt.Println(msg) // "Hello World" は表示される
	}()
	// しかし 'main' 関数のスコープにある 'msg' は更新されない
	time.Sleep(time.Second)
	fmt.Println(msg) // 依然 "Hello" のまま
}

影響

  • 並行処理やコールバックの中で「外側の変数を利用しているつもり」が、実は新しい変数を宣言していた。
  • 変更内容が外側スコープにまったく伝わらない、または外側が意図せず変更されるといった「スレッドセーフ性」以前に変数の扱いがおかしくなる。

解消ポイント

  • ゴルーチンや無名関数内で外側変数を使う時は、「上書きする意図があるのか、新しく別名の変数を使いたいのか」 を明確にする。
  • := ではなく、明示的に外側の変数へ代入する形（=）を取るか、名前を変えるなどして衝突を避ける。

まとめ

  • Goの短い変数宣言（:=）がもたらすシャドーイングは、ちょっとしたコード追加・修正やリファクタリングで簡単に発生する。
  • 変数シャドーイングをすぐに察知できないまま本番リリースしてしまうと、思わぬデータ不正やエラー処理の漏れが深刻な問題へ発展。
  • 特に以下のケースは要注意：
    • エラー変数 err の扱い
    • for ループや if 文ブロック内での更新
    • 複数変数の同時宣言
    • 無名関数やゴルーチンでの外側変数利用
  • 防ぐためには「レビューやリントツールの活用」「変数の使い回し方を意識したコーディング」「テストのカバレッジ強化」など、複合的な対策が必要です。

いずれのケースも、書き手が少しでも “同じ名前を更新したい” と “新しい名前を宣言したい” を取り違える と、シャドーイングバグが忍び寄ります。Goの便利な文法を使いつつ、スコープの概念を常に意識して安全なコードを書く習慣を身につけましょう。

4. 変数シャドーイングを防ぐためのベストプラクティス

宣言と更新を明確に区別する

  • := は「新規変数の宣言＋初期化」 であり、 = は「既存変数への代入」 であることを常に意識する。
  • 「外側の変数を更新したい」場合は必ず = を使う。意図せず := を用いると新規宣言（シャドーイング）に繋がる恐れがある。

同名変数を使わない（使いまわさない）

  • 意図的なシャドーイングが許容される場合はごく稀で、一般的にはバグの原因になることが多い。
  • err などの汎用的な名前は特にシャドーイングしやすい。命名の工夫や、スコープごとに変数名を変えることで事故を減らす。

コードレビュー時のチェック項目に加える

  • チーム開発では、 「同名の変数を内側スコープで := 宣言していないか」 をレビューのチェックリストに含める。
  • 「これは本当に外側変数を上書きしたいのか、それとも新たに変数が必要なのか」をレビューワー同士で会話し確認するだけでも防げるバグは多い。

リントツール・静的解析ツールの活用

  • Goでは、golangci-lint などのリントツールを導入することで、シャドーイングを検出する shadow チェッカーを有効化できる。
  • チェックを自動化しておけば、プルリクエスト時やCI環境でもシャドーイングを早期発見できる。

スコープの可視化を意識したコーディング

  • ブロック（{}）を安易に深くネストさせると、シャドーイングに気づきづらい。ネストを浅く保つ・関数を適切に分割するなど、読みやすいコード構造にするとシャドーイングのリスクが低減する。
  • 無名関数やゴルーチンを使う場合、外側の変数を扱う必要があるのか・別名を使うべきかを検討する。

テストで境界値や例外ケースを網羅する

  • 「テストではシャドーイングの影響が出ないのに、本番でだけおかしくなる」ケースが少なくない。
  • 条件分岐 や 長い入力（境界値） など、さまざまなケースをテストし、シャドーイングによる不具合が潜んでいないかを検証する。

まとめ

  • 変数シャドーイング は、Go言語の短い変数宣言（:=）とスコープの仕組みが生み出す代表的な“落とし穴”。
  • 「外側の変数を更新したつもりが、新しい変数を宣言してしまっている」ことに開発者が気づかないまま、バグの温床になるケースが多い。
  • 特に以下のケースではシャドーイングが発生しやすい：
    1. エラー変数（err）の再宣言
    2. if/for ブロック内での :=
    3. 複数変数を同時に初期化する文（x, err := ...）
    4. 無名関数・ゴルーチン内で外側変数と同名の変数を宣言
  • こうしたトラブルを防ぐには、 宣言と代入を使い分ける意識、コードレビューの徹底、リントツール活用、命名やスコープ設計の工夫 が効果的。
  • テストを包括的に行うことで、シャドーイングを原因とした潜在バグを早めにあぶり出すこと も重要です。

Go言語はシンプルで学習コストが低いと言われますが、スコープや文法の特性を正しく理解していなければ、思わぬ方向で事故を引き起こす可能性があります。ぜひ日々のコーディング・レビュー・テストの場面で、変数シャドーイングという落とし穴を常に意識し、安全で堅牢なGoのコードを生み出していきましょう。

Discussion