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

生徒

「先生、Pythonの関数を書くときにドキュメントを書くってよく聞くんですが、ドキュメントって何ですか？」

先生

「関数の説明を書くことをドキュメントと言います。Pythonでは特に『docstring（ドックストリング）』という形で書きます。関数の使い方や何をするかをプログラムの中に書いておくんですよ。」

生徒

「なんで関数の説明をプログラムの中に書く必要があるんですか？」

先生

「関数を作った本人も、時間が経つと内容を忘れることがありますし、他の人がその関数を使うときにも説明があると分かりやすいです。ドキュメントを書くことは、コードをわかりやすくし、ミスも減らすためにとても大事な作業です。」

生徒

「なるほど。Pythonのdocstringには決まりみたいなものがあるって聞いたのですが？」

先生

「はい、それが『PEP 257』という公式のガイドラインです。docstringの書き方のルールを決めて、みんなが同じように理解しやすくなるようにしています。」

生徒

「それなら安心ですね！具体的にどんな書き方があるんですか？」

先生

「これから詳しく説明していきますね！」

1. docstring（ドックストリング）とは？

docstringとは、Pythonの関数やクラス、モジュールの最初に書く文字列で、そのオブジェクトの説明を記述するものです。三重のダブルクォーテーション"""やシングルクォーテーション'''で囲んで書きます。

例えば、関数の役割や引数、返り値について説明を書くことが多いです。

2. docstringを書く理由とメリット

コードを読みやすくする：関数が何をするのか、すぐわかります。
保守・管理が楽になる：時間が経っても使い方を忘れにくいです。
自動ドキュメント生成に役立つ：ツールを使って説明書を自動作成できます。
チーム開発での情報共有がスムーズになる：誰でも理解しやすいコードになります。

3. PEP 257とは？Pythonのdocstringの公式ルール

PEPとは「Python Enhancement Proposal（Python改善提案）」の略で、PEP 257はdocstringの書き方に関する提案書です。Pythonの公式ドキュメントでも推奨されているルールがまとめられています。

このガイドラインに従うことで、誰が読んでもわかりやすいdocstringが書けるようになります。

4. PEP 257の基本ルールと書き方のポイント

1行目は関数の簡単な説明：短く簡潔に。例えば「数値の階乗を計算する関数」など。
1行目のあとに空行を入れる：説明が複数行ある場合は空行で区切ります。
説明はできるだけわかりやすく書く：専門用語はなるべく使わず、初心者にも理解できる言葉を選びましょう。
引数や戻り値の説明を書く：どんな値を受け取り、どんな値を返すかを明記します。
長すぎないようにする：1行の長さは79文字以内が目安です。
三重のダブルクォーテーション"""で囲む：シングルクォーテーション3つでも良いですが、ダブルクォーテーションが一般的です。

5. docstringの具体的な書き方例

簡単な関数にdocstringを書いてみましょう。


def factorial(n):
    """
    数値nの階乗を計算して返す関数。

    Parameters:
        n (int): 階乗を計算したい非負の整数

    Returns:
        int: nの階乗の結果
    """
    if n == 0:
        return 1
    else:
        return n * factorial(n - 1)

このように、関数の役割、引数（Parameters）、返り値（Returns）を順番に説明しています。

6. docstringの使い方：help()関数で確認する方法

Pythonにはhelp()という便利な関数があり、docstringを書いておくと使い方の説明を画面に表示してくれます。


help(factorial)


Help on function factorial in module __main__:

factorial(n)
    数値nの階乗を計算して返す関数。

    Parameters:
        n (int): 階乗を計算したい非負の整数

    Returns:
        int: nの階乗の結果

プログラムを書いた後に自分や他人が見返すとき、とても役立ちます。