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とは？Python公式の書き方ルール

2. PEP 257とは？Python公式の書き方ルール

PEP 257は、Pythonでdocstring（ドキュメント文字列）を書く際の「公式スタイルガイド」です。PEPとは「Python Enhancement Proposal」の略で、世界中のエンジニアが共通のルールでコードを書けるように定められた標準的な指針のことです。

なぜこのルールが重要なのでしょうか？それは、自分勝手な書き方をすると、後で自分や他の人が見たときに「何のためのコードか」を理解するのに時間がかかってしまうからです。PEP 257という共通言語に従うことで、誰が見ても読みやすく、メンテナンスしやすい高品質なプログラムになります。

初心者の方でも、まずはこの「型」を覚えるだけで、プロっぽいきれいなコードが書けるようになります。具体的なイメージを掴むために、料理のレシピ名と作り方の説明に例えたサンプルを見てみましょう。

def make_curry(meat_type):
    """カレーを作る工程をシミュレートする関数。

    この関数は、指定されたお肉の種類を使ってカレーを調理します。
    野菜のカットから煮込みまで、一連のステップを自動で行います。

    Args:
        meat_type (str): 使用する肉の種類（例：「豚肉」「牛肉」）。
    """
    print(f"{meat_type}のカレーが完成しました！")

このように、「1行目に結論」「2行目は空ける」「3行目以降に詳しく」というリズムを守ることが、PEP 257を攻略する最大のポイントです。このルールを守るだけで、エディタが自動で説明を表示してくれるなど、開発効率が劇的にアップします。

3. 実践！関数のdocstring（ドキュメント文字列）の具体例

3. 実践！関数のdocstring（ドキュメント文字列）の具体例

PEP 257のルールに基づいた、最も標準的で読みやすい関数の書き方を見てみましょう。プログラミング未経験の方でも直感的に理解できるよう、日常的な「買い物」の計算を例に解説します。

def calculate_total_price(price, tax_rate):
    """商品の税込価格を計算して返す関数。

    受け取った商品の価格に消費税率を掛け合わせ、最終的な支払金額を算出します。
    小数点以下の扱いや、複雑な計算をこの関数一つにまとめることができます。

    Args:
        price (int): 商品の本体価格（例：1000）。
        tax_rate (float): 消費税率（例：0.1）。

    Returns:
        int: 消費税を含めた合計金額。
    """
    return int(price * (1 + tax_rate))

このサンプルでは、「概要（1行目）」「空行（2行目）」「詳細説明（3行目以降）」というPEP 257の基本構成を忠実に守っています。特に「Args（引数）」や「Returns（戻り値）」という項目を明記することで、後からコードを見返した時に「この数値は何を意味しているのか？」「結果として何が返ってくるのか？」が一目で判別できるようになります。

このように、構造化された説明文（docstring）を添えるだけで、単なるプログラムの断片が「誰でも使える便利なツール」へと進化します。

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を通じて関数の意図が明確になると、コード全体の把握が容易になり、修正や拡張作業がスムーズに行えるようになります。プログラムを書くうえで説明文を整える作業は決して後回しにすべきではなく、開発者自身の理解を深める重要な工程でもあります。