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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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()関数で確認する方法

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

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

help(factorial)

Help on function factorial in module __main__:

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

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

    Returns:
        int: nの階乗の結果

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

7. docstringを書くときのコツと注意点

7. docstringを書くときのコツと注意点

• 具体的かつ簡潔に書く：何をする関数かが一目でわかるように。
• コードの変更に合わせてdocstringも更新する：説明と実装がずれると意味がありません。
• 読み手を意識する：プログラム初心者や他のチームメンバーが理解しやすい文章を心がける。
• 慣れないうちはシンプルな説明から始める：完璧を目指しすぎず、まずは書く習慣をつけることが大切です。

8. まとめ（※別記事で作成）

8. まとめ（※別記事で作成）

この記事ではPythonの関数docstringの重要性とPEP 257に基づく基本的な書き方を紹介しました。初心者の方もぜひ実際に書いてみて、プログラムをわかりやすく管理しましょう。

まとめ

まとめ

Pythonのプログラミングにおいて、関数のドキュメント（docstring）を記述することは、単なる「説明書き」以上の価値を持っています。本記事で解説してきた通り、docstringは自分自身やチームメンバーへの強力なメッセージとなり、将来のメンテナンスコストを劇的に下げてくれる魔法のツールです。特にPython公式のガイドラインである「PEP 257」を意識することで、誰が見ても直感的に理解できる、プロフェッショナルなコードへと進化させることができます。

docstring記述のポイント再確認

効果的なdocstringを書くためには、まず「何をする関数か」を一言で表す1行目から始めましょう。複雑な処理を行う場合は、その後に空行を挟んで詳細な説明や引数の型、戻り値の内容を記載します。初心者のうちは、記述量よりも「まずは一行でも書くこと」を習慣にすることが上達への近道です。

実戦で使えるサンプルプログラム

これまでに学んだ内容を活かして、複数の数値を受け取り、その平均値を計算する関数にdocstringを適用した例を見てみましょう。リストを引数に取り、エラーハンドリングも含めた実践的な記述です。

def calculate_average(numbers):
    """
    指定された数値リストの平均値を計算して返す関数。

    引数に空のリストが渡された場合は、0.0を返します。

    Parameters:
        numbers (list of float/int): 平均を求めたい数値のリスト

    Returns:
        float: 計算された平均値
    """
    if not numbers:
        return 0.0
    
    total = sum(numbers)
    count = len(numbers)
    return total / count

# 関数の呼び出し例
data = [10, 20, 30, 40, 50]
result = calculate_average(data)
print(f"平均値は {result} です。")

この関数を実行した際の結果は以下のようになります。

平均値は 30.0 です。

docstringを資産にするために

docstringは一度書いて終わりではありません。関数の仕様変更を行った際には、必ずdocstringもセットで更新する癖をつけましょう。古い情報のまま残されたドキュメントは、コードを読み解く際の「罠」になってしまいます。また、Pythonの対話型シェルやIDE（開発環境）の機能をフル活用して、頻繁に help() 関数やホバー表示で内容を確認し、自分の説明が分かりやすいかセルフチェックするのも非常に有効な学習方法です。

綺麗なコードとは、ロジックが優れているだけでなく、読み手への配慮が行き届いているコードのことです。PEP 257という共通言語を身につけることで、世界中のPythonエンジニアと繋がる第一歩を踏み出しましょう。