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

2024-01-242024-07-14

Pythonプログラミングを学び始めたばかりの皆さん、こんにちは！この記事では、PythonのDocStrings(ドキュメントコメント)について詳しく解説します。

DocStringsは、コードの各部分に対する説明を提供するための特別なコメントで、コードの可読性を高め、他の開発者や将来の自分がコードを理解しやすくするために非常に重要です。

目次から探す

DocStringsとは

PythonのDocStrings(ドキュメントコメント)は、コードの各部分に対する説明を提供するための特別な文字列です。

これにより、コードの可読性が向上し、他の開発者や将来の自分がコードを理解しやすくなります。

DocStringsは、関数、クラス、モジュールなどの定義の直後に配置され、Pythonの組み込み関数やツールで簡単にアクセスできます。

DocStringsの定義

DocStringsは、Pythonの関数、クラス、モジュールの最初のステートメントとして記述される文字列リテラルです。

通常、三重引用符("""または''')で囲まれた文字列として記述されます。

以下は、関数に対するDocStringの基本的な例です。

def greet(name):
    """
    指定された名前の人に挨拶をする関数。
    Args:
        name (str): 挨拶する相手の名前。
    Returns:
        str: 挨拶のメッセージ。
    """
    return f"こんにちは、{name}さん！"

この例では、greet関数の直後にDocStringが記述されています。

このDocStringは、関数の目的、引数、戻り値について説明しています。

コメントとの違い

DocStringsと通常のコメント(#で始まる行)にはいくつかの重要な違いがあります。

位置:

DocStringsは、関数、クラス、モジュールの定義の直後に配置されます。
通常のコメントは、コードの任意の場所に配置できます。

アクセス方法:

DocStringsは、Pythonの組み込み関数 help() や __doc__ 属性を使用してプログラム内からアクセスできます。
通常のコメントは、コードの一部としてのみ存在し、プログラム実行時には無視されます。

目的:

DocStringsは、コードの公式なドキュメントとして使用され、関数やクラスの使い方を説明します。
通常のコメントは、コードの特定の部分についての補足説明やメモとして使用されます。

以下に、DocStringsと通常のコメントの違いを示す例を示します。

def add(a, b):
    """
    2つの数値を加算する関数。
    Args:
        a (int): 最初の数値。
        b (int): 2番目の数値。
    Returns:
        int: 2つの数値の合計。
    """
    # ここで2つの数値を加算する
    return a + b

この例では、DocStringは関数の目的と使用方法を説明し、通常のコメントはコードの特定の部分についての補足説明を提供しています。

DocStringsを適切に使用することで、コードの可読性と保守性が大幅に向上します。

次のセクションでは、DocStringsの基本的な書き方について詳しく説明します。

DocStringsの基本的な書き方

DocStrings(ドキュメントコメント)は、Pythonコードにおいて関数、クラス、モジュールの説明を記述するための特別な文字列です。

これにより、コードの可読性が向上し、他の開発者や将来の自分がコードを理解しやすくなります。

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

シングルラインDocString

シングルラインDocStringは、短い説明を1行で記述する場合に使用します。

シングルクォート3つ(”’)またはダブルクォート3つ(“)で囲みます。以下に例を示します。

def add(a, b):
    """2つの数値を加算して返します。"""
    return a + b

この例では、add関数のDocStringが1行で記述されています。

シンプルな関数やメソッドの場合、シングルラインDocStringが適しています。

マルチラインDocString

マルチラインDocStringは、より詳細な説明が必要な場合に使用します。

複数行にわたって記述し、最初の行に簡単な概要を、次の行以降に詳細な説明や使用例を記述します。

以下に例を示します。

def multiply(a, b):
    """
    2つの数値を掛け算して返します。
    引数:
    a (int, float): 最初の数値
    b (int, float): 2番目の数値
    戻り値:
    int, float: 掛け算の結果
    """
    return a * b

この例では、multiply関数のDocStringが複数行にわたって記述されています。

最初の行に関数の概要を、次の行以降に引数や戻り値の詳細な説明を記述しています。

マルチラインDocStringは、関数やクラスが複雑である場合や、使用方法を具体的に示す必要がある場合に非常に有用です。

以上が、DocStringsの基本的な書き方です。

次に、DocStringsの使用場所について解説します。

DocStringsの使用場所

DocStringsは、Pythonコードのさまざまな場所で使用されます。

これにより、コードの各部分が何をするのか、どのように使用するのかを明確に説明することができます。

以下では、DocStringsが使用される主な場所について詳しく説明します。

モジュールのDocString

モジュールのDocStringは、モジュール全体の説明を提供します。

モジュールの先頭に配置され、モジュールが何をするのか、どのように使用するのかを説明します。

モジュールのDocStringは、モジュールがインポートされたときにhelp()関数を使用して表示することができます。

"""
このモジュールは、基本的な数学関数を提供します。
"""
def add(a, b):
    """2つの数値を加算します。"""
    return a + b
def subtract(a, b):
    """2つの数値を減算します。"""
    return a - b

上記の例では、モジュールの先頭にあるDocStringがモジュール全体の説明を提供しています。

クラスのDocString

クラスのDocStringは、クラスの定義の直後に配置され、そのクラスが何をするのか、どのように使用するのかを説明します。

クラスのDocStringは、クラスのインスタンス化やメソッドの呼び出し方法など、クラスの使用方法に関する情報を提供するのに役立ちます。

class Calculator:
    """
    このクラスは、基本的な計算機能を提供します。
    """
    def add(self, a, b):
        """2つの数値を加算します。"""
        return a + b
    def subtract(self, a, b):
        """2つの数値を減算します。"""
        return a - b

上記の例では、クラスCalculatorのDocStringがクラス全体の説明を提供しています。

メソッドと関数のDocString

メソッドと関数のDocStringは、それぞれの定義の直後に配置され、そのメソッドや関数が何をするのか、どのように使用するのかを説明します。

引数や戻り値に関する情報も含めることができます。

def multiply(a, b):
    """
    2つの数値を乗算します。
    Args:
        a (int, float): 1つ目の数値
        b (int, float): 2つ目の数値
    Returns:
        int, float: 乗算の結果
    """
    return a * b

上記の例では、関数multiplyのDocStringが関数の説明、引数の説明、戻り値の説明を提供しています。

このように、DocStringsはモジュール、クラス、メソッド、関数の各場所で使用され、コードの理解を助けるための重要なドキュメントを提供します。

DocStringsのフォーマット

DocStringsは、コードの可読性を高め、他の開発者がコードを理解しやすくするために非常に重要です。

ここでは、DocStringsのフォーマットについて詳しく解説します。

PEP 257に基づく書き方

PEP 257は、PythonのDocStringsに関する公式ガイドラインです。

PEP 257に従うことで、統一された形式でDocStringsを書くことができます。

以下に、PEP 257に基づく基本的なルールを示します。

シングルラインDocString:

短い説明を1行で記述します。

# これはシングルラインのDocStringです。

マルチラインDocString:

複数行にわたる説明を記述します。
最初の行に簡潔な説明を書き、空行を挟んで詳細な説明を続けます。

"""
    これはマルチラインのDocStringです。
    ここに詳細な説明を記述します。
"""

一般的なフォーマットの例

DocStringsの一般的なフォーマットには、以下の要素が含まれます。

簡単な説明
引数の説明
戻り値の説明
例外の説明

これらの要素を含めることで、関数やクラスの使い方が明確になります。

簡単な説明

DocStringの最初の部分には、関数やクラスの簡単な説明を記述します。

この説明は、関数やクラスが何をするのかを一目で理解できるようにするためのものです。

def add(a, b):
    """
    2つの数値を加算します。
    """
    return a + b

引数の説明

関数やメソッドが引数を取る場合、それぞれの引数の説明を記述します。

引数の名前、型、そしてその役割を明確にします。

def add(a, b):
    """
    2つの数値を加算します。
    Args:
        a (int): 最初の数値。
        b (int): 2番目の数値。
    """
    return a + b

戻り値の説明

関数やメソッドが値を返す場合、その戻り値の説明を記述します。

戻り値の型とその意味を明確にします。

def add(a, b):
    """
    2つの数値を加算します。
    Args:
        a (int): 最初の数値。
        b (int): 2番目の数値。
    Returns:
        int: 加算結果。
    """
    return a + b

例外の説明

関数やメソッドが特定の条件で例外を発生させる場合、その例外の説明を記述します。

どのような条件で例外が発生するのかを明確にします。

def divide(a, b):
    """
    2つの数値を除算します。
    Args:
        a (int): 被除数。
        b (int): 除数。
    Returns:
        float: 除算結果。
    Raises:
        ZeroDivisionError: bが0の場合。
    """
    if b == 0:
        raise ZeroDivisionError("除数が0です。")
    return a / b

以上が、DocStringsのフォーマットに関する基本的なガイドラインです。

これらのルールに従うことで、コードの可読性が向上し、他の開発者がコードを理解しやすくなります。

DocStringsの実例

ここでは、実際にDocStringsをどのように書くかについて具体的な例を示します。

関数、クラス、モジュールそれぞれのDocStringの書き方を見ていきましょう。

関数のDocStringの例

関数のDocStringは、その関数が何をするのか、引数や戻り値について説明するために使われます。

以下は、簡単な関数のDocStringの例です。

def add(a, b):
    """
    2つの数値を加算する関数。
    引数:
        a (int, float): 加算する最初の数値。
        b (int, float): 加算する2番目の数値。
    戻り値:
        int, float: 引数aとbの合計。
    """
    return a + b
# 関数のDocStringを表示する
print(add.__doc__)

この関数addは、2つの数値を加算してその結果を返します。

DocStringには、関数の目的、引数の説明、戻り値の説明が含まれています。

クラスのDocStringの例

クラスのDocStringは、そのクラスが何をするのか、どのように使うのかを説明するために使われます。

以下は、簡単なクラスのDocStringの例です。

class Calculator:
    """
    基本的な計算機クラス。
    メソッド:
        add(a, b): 2つの数値を加算する。
        subtract(a, b): 2つの数値を減算する。
    """
    def add(self, a, b):
        """
        2つの数値を加算するメソッド。
        引数:
            a (int, float): 加算する最初の数値。
            b (int, float): 加算する2番目の数値。
        戻り値:
            int, float: 引数aとbの合計。
        """
        return a + b
    def subtract(self, a, b):
        """
        2つの数値を減算するメソッド。
        引数:
            a (int, float): 減算される数値。
            b (int, float): 減算する数値。
        戻り値:
            int, float: 引数aからbを引いた結果。
        """
        return a - b
# クラスのDocStringを表示する
print(Calculator.__doc__)
# メソッドのDocStringを表示する
print(Calculator.add.__doc__)
print(Calculator.subtract.__doc__)

このクラスCalculatorは、基本的な計算機能を提供します。

クラスのDocStringには、クラスの目的とメソッドの一覧が含まれています。

各メソッドにもそれぞれのDocStringがあり、メソッドの目的、引数、戻り値について説明しています。

モジュールのDocStringの例

モジュールのDocStringは、そのモジュールが何をするのか、どのように使うのかを説明するために使われます。

以下は、簡単なモジュールのDocStringの例です。

"""
このモジュールは、基本的な数学関数を提供します。
関数:
    add(a, b): 2つの数値を加算する。
    subtract(a, b): 2つの数値を減算する。
"""
def add(a, b):
    """
    2つの数値を加算する関数。
    引数:
        a (int, float): 加算する最初の数値。
        b (int, float): 加算する2番目の数値。
    戻り値:
        int, float: 引数aとbの合計。
    """
    return a + b
def subtract(a, b):
    """
    2つの数値を減算する関数。
    引数:
        a (int, float): 減算される数値。
        b (int, float): 減算する数値。
    戻り値:
        int, float: 引数aからbを引いた結果。
    """
    return a - b
# モジュールのDocStringを表示する
print(__doc__)

このモジュールは、基本的な数学関数を提供します。

モジュールのDocStringには、モジュールの目的と提供される関数の一覧が含まれています。

各関数にもそれぞれのDocStringがあり、関数の目的、引数、戻り値について説明しています。

以上が、関数、クラス、モジュールそれぞれのDocStringの具体的な例です。

これらの例を参考にして、自分のコードにDocStringを追加してみてください。

DocStringを適切に書くことで、コードの可読性が向上し、他の開発者や将来の自分にとっても理解しやすいコードになります。

DocStringsの活用方法

DocStringsは単にコードにコメントを追加するだけでなく、さまざまな方法で活用することができます。

ここでは、DocStringsの具体的な活用方法について解説します。

help()関数での利用

Pythonの組み込み関数であるhelp()を使用すると、DocStringsを簡単に表示することができます。

これにより、関数やクラスの使い方をすぐに確認することができます。

def greet(name):
    """
    指定された名前に対して挨拶を行う関数。
    Args:
        name (str): 挨拶する相手の名前。
    Returns:
        str: 挨拶のメッセージ。
    """
    return f"こんにちは、{name}さん！"
# help()関数を使ってDocStringを表示
help(greet)

このコードを実行すると、以下のようにDocStringが表示されます。

Help on function greet in module __main__:
greet(name)
    指定された名前に対して挨拶を行う関数。
    Args:
        name (str): 挨拶する相手の名前。
    Returns:
        str: 挨拶のメッセージ。