Appendix B — Peek References with VSCode

Author

Ryo Nakagami

Published

2025-11-20

Modified

2025-11-21

Peek Referenceとは？

Definition B.1 Peek Reference

  • 任意のシンボル（変数，関数，メソッド，クラスなど）が 「どこで参照されているのか」 を編集画面の中で直接確認できる機能
  • VSCodeでは F12 で利用可能(サイドバー表示の場合はShift + Alt + F12 )

きちんと構造化されたプログラムのロジックは順番を追いかけていけば解読することが出来ますが，ユーザーが定義したシンボル（変数，関数，メソッド，クラスなど） がプログラムのどこで参照されているかを理解することは大変です．グローバル変数や関数が定義されているプログラムの場合， 変更したらどこのラインで影響が出るのかを把握できないと保守・デバッグはできません．

Peek Reference を利用すると，こうした 「そのシンボルがどこで使われているのか分からない」という課題をインラインで可視化できるようになります． 参照元を一つずつ探すためにファイルを開き直したり，全文検索で同名の別変数が誤検知される心配もありません．

Peek Reference活用のメリット

メリット 説明
安全にリファクタリングできる 名前変更の前に影響範囲を正確に把握できる
コード理解が圧倒的に早くなる 関数・メソッドがどこで使われているか即座に可視化できる
デッドコードの発見に役立つ 参照が0なら安全に削除できる候補が分かる

Peek ReferenceとPython Language Server

VSCodeが提供するPeak Reference機能は，VSCodeの機能そのものではなく，言語サーバー(Language Server)が提供する情報をもとに動作しています． Python の場合，この役割を担うのが Pylance や Jedi Language Server です．

sequenceDiagram
    participant Dev as 開発者
    participant VSCode as VS Code UI
    participant LSP as Language Server (Pylance)
    participant Code as Pythonコード

    Dev->>VSCode: Peek Reference実行
    VSCode->>LSP: LSPに「このシンボルの定義はどこか？」をリクエスト
    LSP->>Code: コード解析 + 参照情報生成
    Code-->>LSP: 定義位置・参照情報を返す
    LSP-->>VSCode: 定義情報を送信（LSP経由）
    VSCode->>Dev: 該当定義の場所をインラインで表示

Peek Referenceをユーザーが実行するとき，VSCodeの背後では上記のシークエンス図のような処理が行われています．ポイントとしては

  • Python Language Server が参照情報を提供
  • VSCodeとLanguage Serverの間でLSP(Language Server Protocol)を介して情報のやり取りが行われる

そのため，Pylanceが無効だと参照情報を生成できないため，Peek Reference は機能しなくなります．

Pylanceとは？

Definition B.2 Pylance

  • Pyright（Microsoftの静的型チェックツール）ベースのPython Language Server

主な機能

機能 説明
Docstrings表示 関数やクラスのドキュメントを即座に確認可能
Signature Help 関数の引数情報と型情報を補助
Parameter Suggestions 引数候補を提示
コード補完（Code Completion） 変数や関数名の自動補完
自動インポート（Auto-import） 必要なモジュールのインポートを自動追加／削除
リアルタイムのコードエラー・警告表示（Diagnostics） コードを書きながらエラーや警告を確認可能
コードアウトライン表示 ファイル内の構造を一覧化
コードナビゲーション 定義ジャンプ（F12），Peek References など
型チェックモード（Type Checking Mode） 静的型検査で潜在的バグを検出
マルチルートワークスペース対応 複数ルートを持つワークスペースでも解析可能
IntelliCode 互換 AI 補完との連携
Jupyter Notebook 対応 ノートブック環境でも Pylance の解析機能を利用可能
セマンティックハイライト 型情報に基づくシンタックスハイライト

VSCodeでのPeek Referenceの活用

Step 1: Pylanceの設定

settings.json にて以下のラインを追記します

  "python.languageServer": "Pylance",

Step 2: Peek Referenceの実行

Pythonファイルを開き，調査したいシンボル(例: クラスのメソッド)にカーソルを合わせ, F12 を実行します． インラインウィンドウが開き，参照しているコードがハイライトされ一覧表示されます

Peek Reference Example

Escape を押すと，インライン表示を解除できます．また，Alt + Shift + F12 で参照一覧をサイドバーに表示させることも出来ます．

Warning実践にあたっての注意点
  • Pylance が有効であることが必須
  • ファイル数や依存関係が多い場合，初回解析に時間がかかることがある