Python

Pythonのドックストリング(docstring)の書き方

以下では、Pythonにおけるドックストリング（docstring）の基本的な書き方とポイントを解説します。

ドックストリングとは？

ドックストリング(docstring)は、関数・クラス・モジュール・メソッドなどの定義直下に記述する文字列リテラルで、その対象が何を行うのか、どのように使うのかを記述した公式な説明文書です。
help()関数や自動ドキュメント生成ツール（Sphinxなど）を用いることで、このドキュメント文字列が表示・利用されます。

基本的な記述方法

関数の場合の基本形

def function_name(param1, param2):
    """
    関数function_nameの説明文をここに書きます。

    引数:
        param1 (int): param1の説明
        param2 (str): param2の説明

    戻り値:
        bool: 関数が返す結果についての説明
    """
    # 関数本体
    return True
  • ドックストリングは通常 """ (ダブルクォート3つ) で囲みます。
  • 最初の1行目にはその関数/クラス/モジュールの要約的な説明を簡潔に書きます。
  • 2行目に空行を挟むことで可読性を高めます。
  • 以後、詳細な説明、引数や戻り値の説明、例外発生条件、使用例などを記述します。

クラスやメソッドの場合

class MyClass:
    """
    MyClassはXやYを行うクラスです。
    
    詳細な振る舞いについてはここに記述します。
    """

    def method(self, value):
        """
        methodは引数valueを用いて処理を行います。
        
        引数:
            value (str): このメソッドが処理に用いる文字列
        
        戻り値:
            int: 処理結果を整数で返します。
        """
        return len(value)

モジュール（ファイル）の先頭に書く場合

"""
このモジュールはデータ処理用の関数とクラスを提供します。

使用例:
    from mymodule import process_data
    result = process_data("input.txt")

依存関係:
    numpy, requests

ライセンス:
    MIT
"""

ドックストリングのスタイルガイド

PEP 257

Python公式ドキュメンテーションスタイルに関するガイドライン

  • 最初の行は簡潔な要約
  • 2行目は空行
  • 続く行で詳細説明

Googleスタイル

Googleが提案するドキュメントスタイル。引数や戻り値をArgs:, Returns:で明示するなどの形式化

def add(a, b):
    """
    Add two numbers.

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

    Returns:
        int: The sum of a and b.
    """
    return a + b

NumPyスタイル

NumPyやSciPyでよく使われるドキュメント形式。セクションを「Parameters」、「Returns」、「Raises」などで区切る。

def add(a, b):
    """
    Add two numbers.

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

    Returns
    -------
    int
        The sum of a and b.
    """
    return a + b

NumPyスタイルを日本語で書いても大丈夫？

はい、日本語で書いても問題ありません。NumPyスタイルのドックストリングはあくまでフォーマットのガイドラインであり、使用言語を英語に限定するものではありません。そのため、プロジェクトの利用者やチームメンバーが日本語を理解できる環境であれば、日本語のドキュメントを書くことは有用です。

ただし、以下の点に留意するとよいでしょう：

  • プロジェクトの利用者・開発者層を考慮:
    国際的な開発者が参加する、またはグローバルなユーザー層を対象とするプロジェクトでは、英語のドキュメントが好まれることも多いです。
  • 一貫性:
    同一プロジェクト内では、同じ言語で記述することをお勧めします。混在すると可読性やメンテナンス性が下がる可能性があります。
  • NumPyスタイルの構造そのものは維持:
    「Parameters」「Returns」「Raises」などの見出しは英語のままでも、日本語に翻訳しても構いません。ただし、慣れ親しんだセクション名（"Parameters", "Returns"など）はそのまま残した方が、NumPyスタイルに慣れた人にとって理解しやすい場合があります。

例（NumPyスタイル、日本語）:

def add(a, b):
    """
    2つの整数を加算する関数。

    Parameters
    ----------
    a : int
        最初の整数
    b : int
        2番目の整数

    Returns
    -------
    int
        a と b の和
    """
    return a + b

注意点とコツ

  • 一貫性: チームやプロジェクトでドックストリングのスタイルを統一することで、メンテナンス性が向上します。
  • 簡潔さ: 初めの1行は要点を簡潔にまとめ、詳細は後述することで、help()での表示が読みやすくなります。
  • 更新の徹底: コード修正後、ドキュメントが古くならないように必ず更新します。
  • 例外や制約条件も明記: 関数が特定の条件で例外を発生させる場合や、引数にどのような型・条件が求められるかを明記しましょう。

まとめ

  • ドックストリングは関数やクラスの直下に"""で囲んで記述する公式ドキュメント。
  • 最初の1行は簡潔な要約、2行目は空行、その後に詳細を書くと読みやすい。
  • PEP 257、Googleスタイル、NumPyスタイルなど、標準化されたスタイルガイドがある。
  • 一貫性・可読性を重視し、コード変更時には必ずドキュメントも更新することが重要。

このような点に留意しながら、適切なドックストリングを付けることで、他者はもちろん、将来の自分がコードを理解しやすくなります。

-Python