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（ドキュメント文字列）の活用範囲は関数だけではありません。Pythonでは、複数の機能をまとめた「クラス」や、ファイルそのものである「モジュール」の冒頭にも説明を記述します。これにより、コードの規模が大きくなっても「このファイルは何のためのものか」「このクラスで何ができるのか」を迷わず把握できるようになります。

クラスのdocstring

クラスに記述する場合は、クラス名のすぐ下に書きます。そのクラスが持つ役割や、どのようなデータを扱うのかを簡潔にまとめましょう。

class ShoppingCart:
    """オンラインショップの買い物かごを管理するクラス。

    商品の追加、削除、および合計金額の計算を行う機能を提供します。
    プログラミング初心者の方でも、このクラスを使えば複雑な計算を自動化できます。
    """

    def add_item(self, item_name, price):
        """かごに商品を追加する。"""
        print(f"{item_name}をかごに入れました。")

モジュールのdocstring

モジュール（Pythonファイル）のdocstringは、ファイルの1行目から記述します。これは、そのプログラム全体の「表紙」や「目次」のような役割を果たします。

"""
在庫管理システム用モジュール

このファイルには、商品の在庫数を確認したり、
出荷指示を出したりするための関数がまとめられています。
2026年度の最新税制にも対応した計算ロジックを含んでいます。
"""

import datetime
# ここからコードが始まる

5. docstringを記述する絶大なメリット

5. docstringを記述する絶大なメリット

なぜ、プロのエンジニアは忙しい合間を縫ってまでdocstring（ドキュメント文字列）を丁寧に記述するのでしょうか。それは、単なる「メモ書き」以上の価値が、開発効率やコードの品質に直結するからです。

docstringを活用することで得られる主なメリットは、以下の4点に集約されます。

• チーム開発の円滑化：自分以外の人が関数やクラスの使い方を一瞬で理解できるようになり、質問のやり取りを減らせます。
• 「未来の自分」への備忘録：数ヶ月後に自分のコードを読み返した際、「なぜこの処理が必要だったか」を思い出す時間を劇的に短縮できます。
• 開発ツールとの強力な連携：VS Codeなどの高機能エディタ（IDE）では、関数名にマウスを合わせるだけでdocstringの内容がポップアップ表示されます。
• マニュアル作成の自動化：Sphinx（スフィンクス）などのツールを使えば、docstringから本格的なHTMLマニュアルを自動生成できます。

def get_discount_price(price, discount_rate):
    """
    商品の割引後の価格を計算する関数。

    Args:
        price (int): 元の価格
        discount_rate (float): 割引率（0.1 = 10%引き）
    """
    return int(price * (1 - discount_rate))

# 関数名を入力しようとすると、上記の説明が自動で画面に表示されます！

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