【Python】第3章第9回：関数ドキュメント（docstring）の書き方

本記事では、Pythonの関数ドキュメント（docstring）の記述方法について解説します。docstringを正しく記述することで、コードの可読性を向上させ、チーム開発におけるコミュニケーションを円滑にします。

0. 記事の概要

この記事を読むメリット

• docstringの基本を理解：関数やクラスの説明を的確に記述できます。
• 標準フォーマットの習得：PEP 257に準拠した記述方法を学べます。
• コードの可読性向上：他者がコードを理解しやすくなります。

この記事で学べること

• docstringの基本的な書き方
• 標準的なフォーマット例
• 自動ドキュメント生成ツールとの連携

1. docstringの基本

1.1 docstringとは？

docstringは、Pythonの関数やクラス、モジュールの説明を記述する文字列です。関数の最初の行にトリプルクォート（"""または'''）で囲んで記述します。

# docstringの基本例
def greet(name):
    """
    指定した名前で挨拶を行う関数。

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

    Returns:
        str: 挨拶文。
    """
    return f"こんにちは、{name}さん！"

動作解説

1. """で囲まれた部分がdocstringです。
2. Args: 関数の引数を説明します。
3. Returns: 関数の戻り値を説明します。

2. docstringのフォーマット例

2.1 PEP 257に準拠した記述

PEP 257は、docstringの記述方法に関する公式スタイルガイドです。以下は、そのフォーマット例です。

# PEP 257に準拠したdocstring
def calculate_area(length, width):
    """
    矩形の面積を計算する関数。

    この関数は、長さと幅を引数として受け取り、矩形の面積を計算して返します。

    Args:
        length (float): 矩形の長さ。
        width (float): 矩形の幅。

    Returns:
        float: 矩形の面積。
    """
    return length * width

動作解説

1. 簡潔な概要: 最初の行に関数の目的を記述します。
2. 詳細な説明: 2行目以降に関数の動作を説明します。
3. ArgsとReturns: 引数と戻り値を明確に説明します。

3. 自動ドキュメント生成ツールとの連携

3.1 Sphinxを使用したドキュメント生成

Pythonのdocstringは、Sphinxなどのツールを使ってHTML形式のドキュメントに変換できます。

# Sphinx用の設定例
"""
.. automodule:: your_module
    :members:
"""

Sphinxは、docstringをもとにモジュールや関数の詳細を自動的にドキュメント化します。

4. 練習問題

以下の課題に挑戦してみましょう。

1. 関数の引数として与えられた文字列を大文字に変換する関数にdocstringを記述してください。
2. リスト内の要素を合計する関数にPEP 257準拠のdocstringを記述してください。

5. 練習問題の解答と解説

問1の解答例

# 文字列を大文字に変換する関数
def to_uppercase(text):
    """
    文字列を大文字に変換する関数。

    Args:
        text (str): 変換する文字列。

    Returns:
        str: 大文字に変換された文字列。
    """
    return text.upper()

問2の解答例

# リストの要素を合計する関数
def sum_list(numbers):
    """
    リスト内の数値を合計する関数。

    Args:
        numbers (list): 数値が格納されたリスト。

    Returns:
        int: リスト内の数値の合計。
    """
    return sum(numbers)

6. まとめ

docstringは、コードを他者に理解しやすくする重要なツールです。標準フォーマットに従って記述し、Sphinxなどのツールを活用することで、プロジェクト全体のドキュメント品質を向上させましょう。