ふつうは関数とかclassとかに書くdocstringですが、実は変数にもdocstringを書くことができます。
それだけなら普通なのですが、VSCodeでは変数名にマウスオーバーすると 変数の説明をホバー表示 させることができます。
VSCode以外のリッチなIDEを使っていないので、ほかの環境でどうなるのかは知りません…
PyCharmとかどうなるんでしょうか？
（試してみた方いましたらコメントいただけたら助かります！）
環境
- Python 3.11.9
- VSCode 1.96.4
- Pylance 2024.12.1
まず、普通の書き方
こんな感じのPythonスクリプトがあるとします。
今適当に書いた、ふっつーのコードです。
def output_test_txt() -> None: の下にある """テストファイルを一定量出力する関数""" がいつものdocstringですね。
from pathlib import Path
# test.txt のパス
TEST_TXT_PATH = Path("D:/test.txt")
# 出力する最大の行数
OUTPUT_MAX_COUNT = 50
def output_test_txt() -> None:
"""テストファイルを一定量出力する関数"""
with open(TEST_TXT_PATH) as f:
lines = f.readlines()
output_len = min(len(lines), OUTPUT_MAX_COUNT)
for i in range(output_len):
print(f"{i+1}: {lines[i]}")
if __name__ == "__main__":
output_test_txt()
定数 TEST_TXT_PATH, OUTPUT_MAX_COUNT をグローバル変数として定義してあります。
ここで、関数の中で定数 OUTPUT_MAX_COUNT がどういう目的の定数なのか忘却したとします。
なんだっけこの定数…。出力最大数…？文字数？行数？
そこで、マウスオーバーしてみますが…
ホバー（ツールチップ）に説明が出てこない！
関数ならdocstringが表示されるのに…
F12を押して定義した行にジャンプすれば済む話ではありますが、ホバー表示させられるならしたいですよね。
関数は出るんですし…
docstring付きの変数の書き方
以下のように変数の下にdocstringを書くことで、VSCodeが変数とdocstringを結び付けてくれます。
from pathlib import Path
TEST_TXT_PATH = Path("D:/test.txt")
"""test.txt のパス"""
OUTPUT_MAX_COUNT = 50
"""出力する最大の行数"""
def output_test_txt() -> None:
"""テストファイルを一定量出力する関数"""
with open(TEST_TXT_PATH) as f:
lines = f.readlines()
output_len = min(len(lines), OUTPUT_MAX_COUNT)
for i in range(output_len):
print(f"{i+1}: {lines[i]}")
if __name__ == "__main__":
output_test_txt()
変数の下にdocstringを書くのがミソ！
関数なんかと同じ書き方ですね。
この状態で、関数内にある定数の参照にマウスオーバーすると…
出た～！！
これは…便利！！
変数名を変えるときもdocstringを読みながら入力できちゃう！
注意点①：書く場所に注意
docstringは 変数の定義よりも後 に書きます。
たとえば、以下のように普通のコメントっぽく書いてしまうと…
"""test.txt のパス"""
TEST_TXT_PATH = Path("D:/test.txt")
"""出力する最大の行数"""
OUTPUT_MAX_COUNT = 50
このように、上で定義した変数と関連付けされてしまいます。
そっちじゃない！
注意点②：Pylanceだけかもしれない
この挙動がなんなのか簡単に調べてみたのですが、特にそれっぽい情報は出てきませんでした。
もしかしたら、Pylance（Pyright？）のオリジナル仕様かも…？
PyCharmなどの他のIDEで試してみた方いましたら、コメントいただけたら助かります！
追記させていただきます。
注意点③：変数のアノテーションは別に方法があるかも？
上記の方法はVSCodeのホバー上で表示できるというだけであり、それ以上のものではありません。
Pythonインタプリタ上でhelp(OUTPUT_MAX_COUNT)というような感じにしても、int()自体のdocstringが出てきてしまいます。
Help on int object:
class int(object)
| int([x]) -> integer
| int(x, base=10) -> integer
|
:
:
もしかしたら、環境によってはより良い方法があるのかも…？
ないかも？
ChatGPTの出力
ChatGPTに聞いてみたところ、以下の記法でアノテーションを追加できる可能性があるとの出力がありました。
ただ、いずれもVSCodeでは動作を確認できませんでした…。
パターン1とパターン2が表示されないのはわかる（それで表示できたら苦労してない）のですが、パターン3とパターン4がどの程度の根拠に基づいた記法なのかは未確認です。
ハルシネーションにしても、情報が無いよりかはマシかな…と思うので、ついでですし載せておきます。
from typing import Annotated
# パターン1
MY_CONSTANT: int = 100 # パターン2
MY_OTHER_CONSTANT: int = 200 #: パターン3
MY_ANNOTATED_CONSTANT: Annotated[int, "パターン4"] = 300
パターン3はChatGPTによると「Sphinxスタイルの型コメント」とのことです。
どうせVSCode上で表示されないので、詳しく調べていません。
（詳しい方いましたらコメントください）
パターン4は typing.Annotated を使う方法です。
これ、普通は変数の取り得る範囲とかを格納するものだと思うのですが…
docstringみたいな文章を突っ込んじゃっていいものなんでしょうか…？
まとめ
定義した場所とは離れた場所で使う変数は、関数などと同じように変数の下にdocstringを追加しとくことで読みやすいコードになります。
マウスオーバーで確認をよくやるタイプの人にはおススメ！
コメントが下に来るのだけちょっとキモいですが、そういえば条件式 ～ if condition else ～ に初遭遇したときもだいぶキモかったので結局は慣れだと思います。