先生と生徒の会話形式で理解しよう

生徒

「Pythonで関数に説明文をつける方法ってありますか？」

先生

「はい、Pythonではdocstring（ドックストリング）という仕組みを使って関数やクラスに説明文をつけることができます。」

生徒

「それってコメントと何が違うんですか？」

先生

「コメントはコードの実行に影響しませんが、docstringはPythonの組み込み関数help()などで自動的に表示される説明文です。今日はその書き方と、公式ガイドラインであるPEP 257について解説します。」

-

1. docstringとは？

docstringは、Pythonの関数・クラス・モジュールの先頭に記述する文字列で、そのコードの説明や使い方を示します。三重引用符（"""）で囲んで記述するのが特徴です。

例えば、関数の上にdocstringを書くと、その関数の役割や引数・戻り値の説明が残せます。


def greet(name):
    """指定した名前に挨拶する関数。

    Args:
        name (str): 挨拶する相手の名前。

    Returns:
        str: 挨拶のメッセージ。
    """
    return f"こんにちは、{name}さん！"

このように書くと、help(greet)で説明を確認できます。

2. PEP 257とは？

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

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

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

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

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


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

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

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

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

-

5. docstringのメリット

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

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

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

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

先生と生徒の振り返り会話

生徒

「docstringってただの説明文と思っていたけれど、書き方にルールがあると知って驚きました。特に概要と詳細を分ける構成がとても分かりやすかったです。」

先生

「そうですね。PEP 257に沿って書くと統一感が出て、誰が読んでも理解しやすくなります。ドキュメントとしても役立つので、積極的に活用するとよいですよ。」

生徒

「関数の説明を書くことで、自分の考えも整理される気がしました。説明しようとすると、曖昧な部分に気づけるのがいいですね。」

先生

「その通りです。文章化することで設計意図が見えてきますし、コードの品質向上にもつながります。docstringは学習段階から慣れておくと、大規模な開発でも大いに役立ちますよ。」

生徒

「これからは関数を書くときに必ずdocstringも書くようにします！」