Pythonで関数やクラスの説明を書くときに使う「docstring」について、基本的な使い方と公式スタイルガイドに基づいた書き方を整理しました。まだ理解しきれていないところもありますが、自分の学習の記録としてまとめています。
1. docstringとは？
docstring（ドックストリング）は、Pythonで関数・クラス・モジュールなどに説明をつけるための文字列です。定義の直後に三重引用符（""" または '''）で囲んで記述します。
記述したdocstringは help() 関数などから簡単に確認でき、読みやすいコードを書く上で大事な要素になります。
2. docstringの基本的な書き方
単一行docstring
内容が短い場合は1行だけで書けます。
def greet():
"""挨拶を表示する関数"""
print("Hello")
複数行docstring
複数行にわたる説明や、引数・戻り値を説明する場合は、以下のように記述します。
def add(x, y):
"""
2つの数値を加算する関数
Parameters:
x (int): 最初の数
y (int): 2つ目の数
Returns:
int: 合計値
"""
return x + y
3. Python公式スタイルガイド（PEP 257）とは？
Pythonのdocstringのスタイルには公式のガイドラインがあります。それが PEP 257 です。
PEP 257では、docstringに以下のような書き方を推奨しています：
- 三重の ダブルクォート
"""を使う（'''でも可能だが、公式ではダブル推奨） - 1行目には簡潔な要約を書く（ピリオドで終えるとより良い）
- 要約の後に空行を1つ入れて、詳細説明を続ける
- クラスのdocstringは、その目的と振る舞いを説明する
- 関数やメソッドのdocstringには、引数や戻り値の説明も含めると親切
4. help() 関数でdocstringを確認する
docstringは help() 関数で確認することができます。
help(add)
これを実行すると、ターミナル上に関数のdocstringが表示されます。
また、関数やクラスの __doc__ 属性からも直接取得できます。
print(add.__doc__)
5. コメント（#）との違い
Pythonでは # を使ったコメントもありますが、これは実行されない行であり、関数やクラスの説明文とは異なります。
一方、docstringは関数やクラスの属性として記録されるので、外部からも取得できるという違いがあります。
6. ドキュメント生成ツールとの連携（補足）
docstringをしっかり書いておくと、以下のようなツールで自動的にHTML形式のドキュメントを作ることができます。
Sphinx（スフィンクス）
- Python公式ドキュメントでも使われている高機能なツール
- reStructuredTextという形式を使って構成する
- 設定がやや難しいが、自由度が高い
pdoc（ピードック）
- docstringだけで簡単にAPIリファレンスを生成できるツール
- Markdown対応、導入も簡単
pip install pdoc
pdoc your_module.py
このコマンドで your_module.html が生成され、ブラウザで確認できます。
7. よくあるdocstringの注意点
-
"""を使う（PEP 257ではダブルクォート推奨） - 要約 + 空行 + 詳細説明 の順に書くと読みやすい
- 引数・戻り値を書くときは、Googleスタイルなどを参考にするのがわかりやすい
- コードの見直しや他人への共有の際に非常に役立つ
補足：他にもあるdocstringのスタイル
PEP 257のスタイル以外にも、docstringの書き方にはいくつかの形式があります。
- Googleスタイル：引数や戻り値を「Args」「Returns」などのラベルでまとめ、インデントを使って整理する形式です。
- NumPyスタイル：科学技術系ライブラリでよく使われ、見出しと区切り線を使ってセクションごとに整理する形式です。
これらのスタイルは、Sphinxやpdocなどのドキュメント生成ツールにも対応しており、プロジェクトによっては使い分けられていることがあるようです。
まとめ
Pythonのdocstringは、ただの説明というよりも、コードの一部として活用できる便利な機能だと感じました。まだすべてを使いこなせているわけではないですが、今後は関数やクラスを書くときに意識してdocstringをつけていこうと思います。