Pythonの関数のドキュメント（docstring）の書き方！PEP 257のガイドライン

1. docstring（ドキュメント文字列）とは？

1. docstring（ドキュメント文字列）とは？

docstring（ドックストリング）とは、Pythonのプログラム内に記述する「コードのための説明書」のようなものです。関数、クラス、あるいはファイル（モジュール）の先頭に記述することで、そのプログラムが「何をするものか」「どんなデータが必要か」を誰にでもわかりやすく伝える役割を持ちます。

最大の特徴は、一般的なコメント（#）とは異なり、Pythonシステムがその内容を保持している点です。そのため、開発中に内容を確認したり、専用のツールでマニュアルを自動作成したりすることが可能になります。記述する際は、必ずダブルクォート3つ（"""）で囲むのがPythonの標準的なルールです。

まずは、プログラミング初心者の方でも分かりやすい、簡単な挨拶を返すプログラムを例に見てみましょう。

def create_welcome_message(user_name):
    """
    ユーザーに歓迎のメッセージを作成する関数。

    Args:
        user_name (str): 登録されているユーザーの名前。

    Returns:
        str: 「ようこそ、〇〇さん！」という形式の文字列。
    """
    return f"ようこそ、{user_name}さん！"

このようにdocstringを書いておけば、実行環境でhelp(create_welcome_message)と入力するだけで、いつでもこの説明書を呼び出して確認することができます。初心者のうちからこれを書く癖をつけておくと、複雑なプログラムを書く際にも論理的な思考が整理されやすくなるという大きなメリットがあります。

2. PEP 257とは？

2. PEP 257とは？

PEP 257は、Pythonでdocstringを書く際の公式スタイルガイドです。PEPとは「Python Enhancement Proposal（Python拡張提案）」の略で、Pythonの改善や標準化に関する提案書のことです。PEP 257では、docstringの書き方や形式についてのルールが定められています。

主なルールには以下があります。

• docstringは三重引用符（"""）で囲む
• 最初の行には短い概要を書く（ピリオドで終える）
• 2行目は空行を入れる
• 3行目以降に詳細な説明を書く

3. 関数のdocstringの例

3. 関数のdocstringの例

PEP 257に沿った関数のdocstringの例です。

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

    この関数は、与えられた2つの数値を足し合わせ、その合計を返します。

    Args:
        a (int): 最初の数値。
        b (int): 2つ目の数値。

    Returns:
        int: 2つの数値の合計。
    """
    return a + b

概要→空行→詳細説明という流れを守ると、読みやすくなります。

4. クラスやモジュールのdocstring

4. クラスやモジュールのdocstring

docstringは関数だけでなく、クラスやモジュールにも書けます。クラスの場合、クラスの役割や属性の説明を書くと便利です。

class Calculator:
    """簡単な計算機クラス。

    足し算や引き算などの基本的な計算を行います。
    """

    def add(self, x, y):
        """2つの数値を加算して返す。"""
        return x + y

モジュールのdocstringは、ファイルの先頭に記述し、そのファイル全体の説明を書きます。

5. docstringのメリット

5. docstringのメリット

docstringを書くことで、以下のようなメリットがあります。

• コードの可読性が上がる
• 他の人が関数やクラスの使い方を理解しやすくなる
• help()関数で自動的に説明を表示できる
• ドキュメント生成ツール（Sphinxなど）と連携できる

プログラミング初心者でも、docstringを使えば自分のコードをわかりやすく説明できるので、学習にも役立ちます。

6. プログラミング未経験者へのポイント

6. プログラミング未経験者へのポイント

docstringは、いわばコードの「取扱説明書」です。初心者のうちは、引数と戻り値の型、関数が何をするかを簡潔に書くことを意識しましょう。英語で書く習慣も将来役立ちますが、最初は日本語でも構いません。

また、PEP 257のルールを守ることで、将来プロジェクトで他の人と協力するときにもスムーズに作業できます。docstringは単なるメモではなく、プログラムの品質を高める重要な要素です。

まとめ

まとめ

Pythonの関数やクラスに説明文を持たせるためのdocstringは、読みやすいプログラムを作るうえで欠かせない存在であり、特に複雑な機能を扱う際には大きな助けとなります。三重引用符を使って関数やクラスの直下に記述することで、その役割や処理内容、引数や戻り値の意味などを整理でき、同じコードを後から読み返す場合にも、誰かに引き継ぐ場合にも理解が格段に進みます。さらに、docstringはhelp関数でそのまま確認できるため、内部ドキュメントとしての役割を果たしながら、実装者と利用者の橋渡しをしてくれる便利な仕組みです。 また、PEP 257に示されたガイドラインを踏まえて書くことで、統一感のある説明文となり、複数人で開発する際にも迷いが少なくなります。概要を最初に書き、空行を入れて詳細を続ける基本形を守るだけで、読み手にとっての理解しやすさが大きく変わります。さらに、引数や戻り値の説明を丁寧に記述することで、用途がひと目で判断でき、コードの誤用も防げます。docstringは単なる補足情報ではなく、コードの一部としての存在であり、プログラムの品質を高めるための重要な記述であると言えます。 とくに初心者にとって、docstringを書く習慣は思考を整理する力を育てるうえでも効果的です。自分が何を作っているのか、どのような値を扱うのかを文章としてまとめることで、曖昧だった設計意図が明確になり、バグの予防にもつながります。プログラムを理解しやすくするための文章を意識して書くことは、学習の過程で非常に意味が深く、後々の学習や仕事でも役立つ技術です。

docstringの整理に役立つサンプルプログラム

def format_message(text, prefix="情報"):
    """指定された文章に接頭辞をつけて整形する関数。

    この関数は、与えられた文章に任意の接頭辞をつけて返します。
    説明文を整理したいときや、ログ用のメッセージを統一したいときに便利です。

    Args:
        text (str): 整形したい文章。
        prefix (str): 先頭につける言葉。デフォルトは「情報」。

    Returns:
        str: 接頭辞を含めた整形済みの文章。
    """
    return f"{prefix}: {text}"

このサンプルでは、docstringの構成として概要、空行、詳細説明という流れを守りながら、引数と戻り値の説明を丁寧に記述しています。こうした構造を繰り返し使うことで、読み手が迷わない一貫したスタイルのコードを維持できます。また、docstringを通じて関数の意図が明確になると、コード全体の把握が容易になり、修正や拡張作業がスムーズに行えるようになります。プログラムを書くうえで説明文を整える作業は決して後回しにすべきではなく、開発者自身の理解を深める重要な工程でもあります。