【基本】PythonでDocscringを正しく書こう

（最終更新日：2023年9月）

✔このような方へ向けて書かれた記事となります

「Pythonのdocstringって何だろう？」
「docstringの書き方や使い方が知りたい」
「docstringを活用したコード例が見たい」

✔当記事を通じてお伝えすること

Pythonのdocstringの概要
docstringの書き方とその活用方法
docstringを用いた実践的なコード例

当記事では、Pythonのdocstringの基本概念から、その書き方や活用方法について、具体的なコード例を交えてわかりやすく解説しています。

ぜひ最後までお読みいただき、docstringの活用をマスターしてください。

筆者プロフィール

【現職】プロダクトマネージャー

【副業】ブログ（月間20万PV）/YouTube/Web・アプリ制作

「プログラミング × ライティング × 営業」の経験を活かし、30後半からのIT系職へシフト。現在はプロダクトマネージャーとして、さまざまな関係者の間に入り奮闘してます。当サイトでは、実際に手を動かせるWebアプリの開発を通じて、プログラミングはもちろん、IT職に必要な情報を提供していきます。

【当ブログで紹介しているサイト】

当サイトチュートリアルで作成したデモ版日報アプリ

Django × Reactで開発したツール系Webアプリ

✔人に見せても恥ずかしくないコードを書こう

「リーダブルコード」は、わかりやすく良いコードの定義を教えてくれる本です。

見るからにきれいなコードの書き方
コードの分割方法
変数や関数の命名規則

エンジニアのスタンダートとすべき基準を一から解説しています。

何回も読むのに値する本なので、ぜひ手にとって読んでみてください。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック

created by Rinker

Docstringの基本概念

ここでは、「Docstring」の基本概念についてお伝えしていきます。

Docstringについて理解し、適切に使えるようになることで、コードの可読性を向上させ、他の開発者と円滑にコミュニケーションを取ることが可能です。

Docstringとは？
Docstringがもたらす利点

Docstringとは？

PythonのDocstringは、関数、クラス、モジュールなどの定義直後に記述する文字列のことを指します。

トリプルクォート（”””）で囲まれ、該当するコードブロックの説明や使用法を記載します。

以下に簡単な例を示します。

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

    Parameters:
    a (int): 1つ目の数値
    b (int): 2つ目の数値

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

ここでは、add関数の直後にDocstringが記述されており、この関数が何をするのか、どのような引数を受け取り、何を返すのかが明確に記述されています。

Docstringがもたらす利点

Docstringがもたらす利点として以下の3つをご覧いただきます。

コードの可読性向上
ドキュメンテーションの作成
自動化テストの構築

コードの可読性向上

Docstringの利点のひとつは、コードの可読性を大幅に向上させることです。

以下のようなことを共有し、ドキュメンテーションを参照することなく直接コードから読み取ることが可能になります。

どの関数が何をするのか
どのクラスが何を表すのか
なぜそのような機能をつけたのか

ドキュメンテーションの作成

DocstringはAPIドキュメンテーションの生成にも利用できます。

例えば、Pythonのhelp()関数はDocstringを取得して表示できます。

上記のadd関数に対してhelp(add)を実行すると、Docstringが表示されます。

>>> help(add)
Help on function add in module __main__:

add(a:int, b:int) -> int
    2つの数値の和を計算します。

    Parameters:
    a (int): 1つ目の数値
    b (int): 2つ目の数値

    Returns:
    int: 2つの数値の和

これにより、他の開発者がadd関数の目的や使用方法をすぐに理解することができます。

自動化テストの構築

doctestは、ドキュメント文字列内のインタラクティブな例を使用して、コードのテストをおこなうためのモジュールです。

以下に、上記のadd関数のドキュメント文字列にdoctestの例を追加します。

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

    Parameters:
    a (int): 1つ目の数値
    b (int): 2つ目の数値

    Returns:
    int: 2つの数値の和

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    >>> add(0, 0)
    0
    """
    return a + b

>>>の後に関数を呼び出すコードを書き、その次の行に期待される結果を書きます。

doctestは、この期待される結果と実際の結果を比較して、テストが成功したかどうかを判断してくれるのです。

このdoctestを実行するには、以下のようなコードをファイルの最後に追加します：

if __name__ == "__main__":
    import doctest
    doctest.testmod()

このコードを含むファイルを実行すると、doctestはドキュメント文字列内のテストを実行し、結果を表示します。

PythonとDocstring

次に、PythonとDocstringの関係について深く掘り下げていきます。

「Docstring」はPythonの一部であり、その書き方や用途を理解することで、より良いコードを書けるようになるでしょう。

Docstringと文字列
PEP8とPEP257に基づく書き方
基本的な記述方法

Docstringと文字列

PythonのDocstringは、特別な場所に記述された文字列です。

具体的には、関数やクラス、モジュール、メソッドの定義の直後に位置しています。

これらの定義が実行された時、Pythonは直後の文字列を自動的にDocstringとして認識し、その定義（関数、クラスなど）のdoc属性として格納します。

以下の例では、関数addのDocstringをdoc属性を通じて表示しています。

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

    Parameters:
    a (int): 1つ目の数値
    b (int): 2つ目の数値

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

print(add.__doc__)

このコードを実行すると、関数addのDocstringがそのまま出力されます。

PEP8とPEP257に基づく書き方

Docstringの書き方には、Pythonの公式スタイルガイド、PEP 8とPEP 257の指示に従うべきです。

これらはPythonコミュニティに広く受け入れられている標準であり、それに従うことでほかのPython開発者との協業がスムーズに進むでしょう。

PEP 257：Docstringに関する規約
PEP 8：Python全般のコードスタイルに関する規約

例えばPEP 8によれば、Docstringは常にトリプルダブルクォート（”””）を使って記述すべきで、その開始と終了は新しい行に置くべきです。

また、PEP 257はDocstringの内容に関する詳細なガイドラインを提供しています。

基本的な記述方法

PythonのDocstringは、その目的や形式により異なる書き方が求められます。

基本的な記述方法は次の通りです。

最初の行は、そのオブジェクト（関数、メソッド、クラス）の短い概要を記述します。
すべての主要な情報はここに集約され、一行で完結すべきです。

概要の後、一行空けてから、より詳細な説明を記述します。
この部分では、オブジェクトの挙動、引数の詳細、戻り値の詳細、エラーの挙動、関連するサイドエフェクトなどについて詳しく説明します。

以下がその具体例です。

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

    aとbの数値の和を計算し、その結果を返します。aとbはどちらも整数である必要があります。
    浮動小数点数を指定した場合、ValueErrorが発生します。

    Parameters:
    a (int): 1つ目の数値
    b (int): 2つ目の数値

    Returns:
    int: 2つの数値の和

    Raises:
    ValueError: aまたはbが整数でない場合
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError('Both a and b need to be integers.')

    return a + b

ここでは、最初の行が短い概要、次のパラグラフが詳細な説明、その後に引数と戻り値、最後に発生する可能性のあるエラーを説明しています。

Docstringの表示・出力方法

Pythonでは、Docstringはコードの中で簡単に取得して表示することが可能です。

さまざまな方法がありますので、それぞれについて詳しく見ていきましょう。

doc属性
組み込み関数help()
IDEやエディタでの表示

doc属性

Pythonの各オブジェクトには、docという特殊な属性が存在します。

これはそのオブジェクトのDocstringを保持するもの。

次のようにして、任意のオブジェクトからDocstringを取得することが可能です。

print(add.__doc__)

上記のコードは、先程定義したadd関数のDocstringを出力します。

組み込み関数help()

Pythonには、組み込み関数help()が用意されており、これを使用すると任意のオブジェクトの詳細な情報を取得できます。

この情報には、オブジェクトの型、使用方法、そしてDocstringが含まれます。

help(add)

関数の定義、Docstring、そして関数が受け入れる引数についての情報が含まれます。

IDEやエディタでの表示

さまざまな統合開発環境（IDE）やエディタでは、自動的にDocstringを取得して表示する機能があります。

これにより、開発者は関数の使用法やクラスの方法をすぐに理解することができます。

Jupyter Notebook
VSCode

Jupyter Notebook

Jupyter Notebookでは、関数名の後に?をつけてセルを実行することで、その関数のDocstringを表示できます。

add?

また、Shift + Tabのキー操作も同じ目的で使用できます。

VSCode

VSCodeでは、関数名やメソッド名にマウスカーソルを合わせるだけで、そのDocstringがポップアップとして表示されます。

これにより、関数やメソッドの使用法を確認しながらコーディングをおこなえます。

Docstringを用いたテストとスタイル

Docstringはコードの説明だけでなく、テストやドキュメンテーションの生成にも使われます。

また、標準的な書き方がいくつか提案されており、それぞれが異なる状況で役立ちます。

doctestによるテスト
引数や返り値の書き方のスタイル

doctestによるテスト

Pythonのdoctestモジュールを使用すると、Docstring内に記述したインタラクティブなPythonセッションをテストとして使用できます。

これにより、一部の単純なテストはDocstring内で完結させることが可能になり、関数の動作例を同時に示すことも可能です。

以下に具体的な例を示します：

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

    >>> add(1, 2)
    3
    >>> add(-1, 5)
    4
    >>> add(3, 3)
    6

    Parameters:
    a (int): 1つ目の数値
    b (int): 2つ目の数値

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

このDocstring内には、関数addの使用例が>>>というプロンプトと共に記述されています。

これらの例はdoctestによってテストとして扱われ、実際の関数の挙動と照らし合わせるのです。

具体的には、以下のコマンドでこれらのテストを実行できます。

if __name__ == "__main__":
    import doctest
    doctest.testmod()

これを実行すると、Docstring内の各テストが実行され、結果がDocstring内の記述と一致するか確認されます。

一致しない場合、テストが失敗と見なされます。

引数や返り値の書き方のスタイル

Docstringの書き方は数多くありますが、ここではPythonコミュニティで広く使われている3つのスタイルを紹介します。

reStructuredText（reST）スタイル
NumPyスタイル
Googleスタイル

これらのスタイルは引数、返り値、エラーなどの記述方法を定めています。

どのスタイルを選ぶかは、個々のプロジェクトやチームの好みによるところが大きいです。

reStructuredText（reST）スタイル

reStructuredText（reST）スタイルはPythonの公式ドキュメンテーションでも使用されており、明確な構造を持つことが特徴です。

Sphinxというドキュメンテーションジェネレータとの相性が良いため、大規模なプロジェクトでよく採用されます。

以下がその例です。

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

    :param a: 1つ目の数値
    :type a: int
    :param b: 2つ目の数値
    :type b: int
    :return: 2つの数値の和
    :rtype: int
    :raises ValueError: aまたはbが整数でない場合
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError('Both a and b need to be integers.')

    return a + b

ここでは、paramで引数を説明し、typeでその型を示しています。

戻り値はreturnとrtypeで説明し、例外はraisesを使っています。

NumPyスタイル

NumPyスタイルはその名の通り、科学計算ライブラリNumPyで採用されています。

科学計算やデータ分析の領域でよく使われる形式です。

このスタイルの特徴は、引数と戻り値の説明がセクションごとに分けられ、読みやすい形式になっていること。

以下に具体的な例を示します。

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

    Parameters
    ----------
    a : int
        1つ目の数値
    b : int
        2つ目の数値

    Returns
    -------
    int
        2つの数値の和

    Raises
    ------
    ValueError
        aまたはbが整数でない場合
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError('Both a and b need to be integers.')

    return a + b

Googleスタイル

Googleスタイルはその名の通り、Googleが提唱するDocstringのスタイルで、非常に読みやすいとされています。

引数と戻り値の説明が明確に分けられ、その型も併記する方法です。

また、シンプルなマークアップが特徴的で、見た目の美しさも重視されています。

以下がその具体例です。

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

    Args:
        a (int): 1つ目の数値
        b (int): 2つ目の数値

    Returns:
        int: 2つの数値の和

    Raises:
        ValueError: aまたはbが整数でない場合
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError('Both a and b need to be integers.')

    return a + b

Googleスタイルでは、「Args」、「Returns」、「Raises」のようにセクションを明示的に分けて記述。

それぞれのセクション内では、引数名や戻り値の型の後にその説明を書きましょう。

このスタイルは見た目がシンプルでありながら、必要な情報をしっかりと伝えることができます。