Python | 「英語のdocstringフォーマット（Google/Numpyスタイル）」について

要点

Pythonのdocstringには「Googleスタイル」と「NumPyスタイル」がよく使われます。どちらも関数やクラスの説明を整理して書くためのフォーマットで、チーム開発や自動ドキュメント生成に役立ちます。

Googleスタイルのdocstring

• 特徴：シンプルで読みやすい。短い関数や初心者に向いている。
• 書き方：Args:, Returns:, Raises: などの見出しを使う。

例

def multiply(a, b):
    """Multiply two numbers.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The product of a and b.
    """
    return a * b

def multiply(a, b):
    """Multiply two numbers.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The product of a and b.
    """
    return a * b

👉 ポイント

• 引数は Args: の下にインデントして列挙
• 戻り値は Returns: に型と説明を書く
• 例外を投げる場合は Raises: を使う

NumPyスタイルのdocstring

• 特徴：科学技術系ライブラリ（NumPy, pandas, SciPyなど）でよく使われる。
• 書き方：Parameters, Returns, Raises などを「セクション見出し」として書く。

例

def multiply(a, b):
    """
    Multiply two numbers.

    Parameters
    ----------
    a : int
        The first number.
    b : int
        The second number.

    Returns
    -------
    int
        The product of a and b.
    """
    return a * b

def multiply(a, b):
    """
    Multiply two numbers.

    Parameters
    ----------
    a : int
        The first number.
    b : int
        The second number.

    Returns
    -------
    int
        The product of a and b.
    """
    return a * b

👉 ポイント

• セクション名の下に「型 : 説明」の形式で書く
• 見出しの下に ----- を入れるのが特徴
• 数学やデータ分析系の関数に向いている

まとめ

• Googleスタイル：シンプルでわかりやすい。小規模プロジェクトや初心者向け。
• NumPyスタイル：詳細に書ける。科学技術系や大規模プロジェクト向け。
• どちらも 統一して使うことが大事。チームでルールを決めておくと良い。

💡 実践アイデア：
自分の書いた関数に Googleスタイル と NumPyスタイル の両方でdocstringをつけてみると、違いがよく理解できます。