【Python】DocStrings(ドキュメントコメント)の書き方を解説

この記事では、Pythonのプログラム内に埋め込むことができるドキュメントコメントであるDocStringsの書き方とフォーマットについて解説します。

DocStringsを使うことで、他の開発者や自分自身がコードを理解しやすくなり、効果的な開発をサポートすることができます。

初心者の方でもわかりやすく、具体的なサンプルコードとともに解説していきますので、ぜひ参考にしてください。

目次から探す

DocStringsとは

DocStrings(ドキュメントコメント)は、Pythonプログラムの中に埋め込まれたコメントのことです。

これは、関数やクラス、モジュールなどの定義の直前に記述され、その要素の説明や使い方、引数や戻り値の説明などを記述するために使用されます。

DocStringsは、プログラムの可読性を向上させるだけでなく、自動ドキュメンテーションツールやIDEの補完機能などと組み合わせて、より効果的な開発をサポートする役割も果たします。

Pythonでは、一重引用符(‘)または三重引用符(”’または“)を使用してDocStringsを作成することができます。

一重引用符を使用する場合は、単一行のコメントを記述することができます。

一方、三重引用符を使用する場合は、複数行のコメントを記述することができます。

DocStringsの書き方にはいくつかのスタイルがあります。

例えば、Googleスタイル、NumPyスタイル、reStructuredTextスタイルなどがあります。

それぞれのスタイルには、特定のフォーマットや規則があります。

DocStringsは、プログラムの可読性を向上させるために重要な役割を果たします。

適切なドキュメントコメントを記述することで、他の開発者がコードを理解しやすくなります。

また、自動ドキュメンテーションツールを使用することで、ドキュメントを自動的に生成することもできます。

DocStringsの書き方

DocStringsはPythonのソースコード内に記述されるドキュメントコメントのことです。

プログラムの機能や使い方、引数や戻り値の説明などを記述することができます。

ここでは、DocStringsの書き方について解説します。

一重引用符を使った書き方

一重引用符を使ったDocStringsは、シングルクォートで囲まれた文字列として記述します。

以下は一重引用符を使ったDocStringsの例です。

def add(a, b):
    '''
    2つの数値を足し合わせる関数

    Parameters:
    a (int): 足される数値
    b (int): 足す数値

    Returns:
    int: 2つの数値の和
    '''
    return a + b

三重引用符を使った書き方

三重引用符を使ったDocStringsは、ダブルクォートまたはシングルクォートで囲まれた複数行の文字列として記述します。

以下は三重引用符を使ったDocStringsの例です。

def subtract(a, b):
    """
    2つの数値を引き算する関数

    Parameters:
    a (int): 引かれる数値
    b (int): 引く数値

    Returns:
    int: 2つの数値の差
    """
    return a - b

マルチラインのDocStringsの書き方

マルチラインのDocStringsは、複数行の文字列として記述します。

以下はマルチラインのDocStringsの例です。

def multiply(a, b):
    """
    2つの数値を掛け算する関数

    Parameters:
    a (int): 掛けられる数値
    b (int): 掛ける数値

    Returns:
    int: 2つの数値の積
    """
    return a * b

以上がDocStringsの書き方の例です。

DocStringsを適切に記述することで、他の開発者や自分自身がコードを理解しやすくなります。

次はDocStringsのフォーマットについて解説します。

DocStringsは関数やクラスの定義の直後に記述することが一般的です。

また、DocStringsの内容はPEP 257に従って記述することが推奨されています。

DocStringsのフォーマット

DocStringsは、Pythonのコード内に埋め込まれたドキュメントコメントのことです。

ドキュメントコメントは、関数やクラス、モジュールなどの定義の直前に記述され、その要素の説明や使い方、引数や戻り値の説明などを記述するために使用されます。

Pythonでは、いくつかの標準的なDocStringsのフォーマットがあります。

ここでは、代表的な3つのフォーマットについて解説します。

Googleスタイルのフォーマット

GoogleスタイルのDocStringsは、Googleが推奨するフォーマットです。

以下は、GoogleスタイルのDocStringsの例です。

def add_numbers(a, b):
    """
    2つの数値を加算する関数

    Args:
        a (int): 加算する数値
        b (int): 加算する数値

    Returns:
        int: 加算結果
    """
    return a + b

GoogleスタイルのDocStringsでは、関数の説明をトリプルクォートで囲み、引数と戻り値の説明をArgsReturnsのセクションで記述します。

引数と戻り値の説明には、型情報や説明文を記述することができます。

NumPyスタイルのフォーマット

NumPyスタイルのDocStringsは、NumPyライブラリで広く使用されているフォーマットです。

以下は、NumPyスタイルのDocStringsの例です。

def multiply_arrays(arr1, arr2):
    """
    2つの配列の要素ごとの積を計算する関数

    Parameters
    ----------
    arr1 : numpy.ndarray
        1つ目の配列
    arr2 : numpy.ndarray
        2つ目の配列

    Returns
    -------
    numpy.ndarray
        要素ごとの積の結果の配列
    """
    return arr1 * arr2

NumPyスタイルのDocStringsでは、関数の説明をトリプルクォートで囲み、引数と戻り値の説明をParametersReturnsのセクションで記述します。

引数と戻り値の説明には、型情報や説明文を記述することができます。

また、引数の説明には、Parametersの前に----------を記述することで区切り線を表示することもできます。

reStructuredTextスタイルのフォーマット

reStructuredTextスタイルのDocStringsは、Pythonの標準ドキュメンテーションツールであるSphinxによって使用されるフォーマットです。

以下は、reStructuredTextスタイルのDocStringsの例です。

def divide_numbers(a, b):
    """
    2つの数値を除算する関数

    :param a: 除算する数値
    :type a: float
    :param b: 除算する数値
    :type b: float
    :return: 除算結果
    :rtype: float
    """
    return a / b

reStructuredTextスタイルのDocStringsでは、関数の説明をトリプルクォートで囲み、引数と戻り値の説明を:param:returnのタグで記述します。

引数と戻り値の説明には、型情報や説明文を記述することができます。

以上が、代表的な3つのDocStringsのフォーマットの例です。

これらのフォーマットを使って、Pythonのコードにわかりやすいドキュメントコメントを記述することができます。

目次から探す