Pythonのドキュメンテーション文字列（docstring）

Pythonでプログラムを書くとき、「この関数は何をするのか？」を後から読み返してすぐに理解できるようにしておくことはとても大切です。 そのために使われるのがドキュメンテーション文字列（docstring）です。

ドキュメンテーションを正しく書くことで、コードの可読性や保守性が大幅に向上し、他の開発者はもちろん、未来の自分自身もコードを理解しやすくなります。 ここでは、ドキュメンテーション文字列の基本から実際の使い方まで、初心者向けに分かりやすく解説していきます。

ドキュメンテーション文字列の基本的な書き方

ドキュメンテーション文字列は、関数・クラス・モジュールを定義した直後に記述します。書き方はとてもシンプルで、三重引用符（''' または """）で囲むだけです。

def 関数名(引数):
    """
    関数の説明

    引数:
    引数名 (型): 引数に関する説明

    戻り値:
    戻り値の型: 戻り値に関する説明
    """
    # 関数の処理
    return 戻り値

このように書くことで、関数の説明、引数の情報、戻り値の型や意味をコード内に明示できます。特にチーム開発では、「関数を読むだけで目的が分かる」 というのが非常に重要です。

それでは、具体的な例を見てみましょう。

def add(a, b):
    """
    2つの数を加算して結果を返します。

    引数:
        a (int or float): 加算する最初の数
        b (int or float): 加算する2番目の数

    戻り値:
        int or float: aとbの合計値
    """
    return a + b

# 関数を呼び出して結果を表示
result = add(3, 5)
print(result)  # 出力: 8

この関数は a と b という2つの引数を受け取り、その合計を返します。

重要なのは、その直後に書かれているドキュメント文字列です。ここには関数の目的（2つの数を加算すること）、引数の型と意味、そして戻り値がきちんと説明されています。これにより、コードを見ただけでこの関数が何をするのかがすぐに理解できます。

ドキュメント文字列の確認

ドキュメント文字列はただの文字列ではなく、Python内部で管理されています。そのため、後から doc という属性を使って内容を確認することができます。

#関数の定義
def add(a, b):
    """
    2つの数を加算して結果を返します。

    引数:
        a (int or float): 加算する最初の数
        b (int or float): 加算する2番目の数

    戻り値:
        int or float: aとbの合計値
    """
    return a + b

#ドキュメント文字列の確認
print(add.__doc__)

これを実行すると、add関数のドキュメント文字列がそのまま表示されます。

組み込み関数のドキュメント文字列を見てみる

ドキュメント文字列は自分で書く関数だけでなく、Pythonの標準ライブラリや組み込み関数にも用意されています。

たとえば、len()関数のdocstringを見てみましょう。

print(len.__doc__)

これを実行すると、以下のように表示されます。

Return the number of items in a container.

len()が「オブジェクトの長さ（要素数）を返す関数」であることが表示されます。このように、ドキュメント文字列は 関数の説明書のような役割を果たしています。

まとめ

ドキュメンテーション文字列は、コードの品質を向上させるために非常に重要です。良いドキュメント文字列を書くことで、他の開発者や将来の自分がコードを理解しやすくなります。以下は、良いドキュメント文字列を書くためのポイントです。

• 関数の目的を明確にする
• 引数と戻り値の型と説明を記載する
• 可能であれば、使用例を追加する

ドキュメント文字列を活用して、あなたのコードの可読性を向上させましょう。