PythonのDocstring（ドキュメンテーション文字列）とは？基本から使い方まで解説

Pythonプログラムでは、コードの理解を助けるためにコメントを記述できます。しかし、特定のコメントやコードの該当箇所を探すには、検索機能（Ctrl+F）を使って何行にもわたってスクロールしなければならず、効率的とは言えません。さらに、ある単語がコードのどの部分と関連しているのかを即座に把握する手段もありません。

こうした課題を解決してくれるのがDocstring（ドキュメンテーション文字列）です。Docstringは、関数・モジュール・クラス・メソッドの定義直後に記述された文字列に直接アクセスできる仕組みで、コードのドキュメント化に非常に役立ちます。

Docstringを出力する

オブジェクトの定義直後に文字列を宣言すると、その文字列は__doc__属性として自動的にそのPythonオブジェクトに関連付けられます。__doc__属性を参照することで、いつでもドキュメントを取り出せます。以下の例を見てみましょう。

例

def Add_nums(x):
    '''Add a number to itself.'''
    return x + x
print(Add_nums.__doc__)

実行結果

上記のコードを実行すると、次のような結果が得られます。

Add a number to itself.

1行Docstringと複数行Docstringの違い

1行Docstring（シングルライン）は、名前の通り1行で完結する短い説明文です。あまり詳細に書きすぎず、簡潔な要約にとどめるのがポイントです。文字列の先頭と末尾を三重引用符（''' または """）で囲みます。前述の例は1行Docstringにあたります。

複数行Docstring

モジュールや関数をより詳しく説明したい場合には、複数行Docstringを使用します。複数行Docstringでは、まず1行Docstringと同じように要約行を記述し、その後に空行を1行挟んでから、より詳細な説明を続けます。

例

def Fibonacci(n):
    '''The Fibonacci numbers are the numbers in the following integer sequence.
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, ...'''
    return n
print(Fibonacci.__doc__)

実行結果

上記のコードを実行すると、次のような結果が得られます。

The Fibonacci numbers are the numbers in the following integer sequence.
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, ...

Python組み込みオブジェクトのDocstring

関数やモジュールなど、Pythonが標準で提供している組み込みオブジェクトについても、クラス名に__doc__を付けるだけで、関連付けられたドキュメントに簡単にアクセスできます。

例

print(list.__doc__)

実行結果

上記のコードを実行すると、次のような結果が得られます。

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list.
The argument must be an iterable if specified.

Docstringにおけるインデントのルール

Docstringの最初の行（最初の改行まで）に含まれるインデントは意味を持たず、自動的に削除されます。一方、それ以降の行の相対的なインデントは保持されます。つまり、Docstring全体は、最初の行の引用符と同じ位置に揃えてインデントされることになります。このルールを守ることで、整形された読みやすいドキュメントを維持できます。