【Python入門】関数にdocstringでドキュメントを付ける

ここまでPythonの関数を見てきました。

Pythonの関数にはそれぞれ使い方があります。組み込み関数はもちろんですが、自分で作った関数も使い方がわからないと使えません。

自分が使うだけなら問題無いかも知れませんが、他の人がコードを見てもわかるようにしておく必要があります。

ここで必要になってくるのが、docstringです。

ここではPythonでのdocstringの書き方について見ていこうと思います。

関数のdostringの見方

関数の意味や使い方がわからないと使うことができません。ではどうすればその関数の意味を理解することができるのでしょうか？それは関数のdocstringを見ることで理解することができます。

これまで出てきた組み込み関数をいくつか使って、docstringを見てみましょう。

docstringを見るには、help()関数を使うか、__doc__を使ってprint出力するで見ることができます。

ここでは、len()、range()関数のdocstringを見ていこうと思います。

まずはhelp()関数をの中に関数名を入れて見ることができます。

help(len)
help(range)

対話型シェルで見ていきましょう。

help()関数を使うと説明のドキュメントだけでなく、メソッドの定義の説明までを整形された形で表示されます。

次はprint()関数で、__doc__を使って見ていきます。調べる関数名にドット（.）で__doc__を繋げて表示させます。

print(len.__doc__)
print(range.__doc__)

対話型シェルで見てみましょう。

こちらは、関数の説明のドキュメントだけがそのまま表示されています。わからない関数は、こうやって内容を調べることができます。もちろん、リファレンスサイトなどで確認しても良いですけどね。

docstringの書き方

では、実際に関数のドキュメント（docstiring）はどう書けばいいのか、見ていくことにしましょう。

docstringの書き方は、3連のクォーテーションで説明のドキュメントを囲み、関数を定義したブロックコードの一番最初に入れ込むという約束になっています。

具体的に関数を作ってdocstringを入れてみましょう。

def say_hello_twice(name):
    """2回繰り返して挨拶をする関数です。
    :param name: 文字列で呼び名
    :return: nameをつけて、ハロー！と2回繰り返します。
    """
    return ("ハロー! "+ name  +'! ') * 2

3連のクォーテーションで囲んで説明を書いているように、挨拶を2回繰り返す関数を書いてみました。

この関数自体を実行してみましょう。nameには「Python」と入れてみます。合わせて、help関数と__doc__を使った出力も一緒に見てみましょう。

r = say_hello_twice("Python")
print(r)

help(say_hello_twice)

print(say_hello_twice.__doc__)

対話型シェルで見てみましょう。

挨拶が2回実行されて、help()で整形されたドキュメントと__doc__を使ったドキュメントが表示されているのがわかります。

ドキュメントの書き方にはPythonでのルールもあるようですが、ここではトリプルクォートで囲んだものを関数のブロックの先頭に置くということだけとりあえず理解しておきましょう。

まとめ

関数の内容を知りたいときリファレンスを見るのもいいですが、help関数を使うか、__doc__を使ってdocstringを見ることで関数の内容を知ることができます。

自分で関数を作った時にも、他の人がコードを見てもわかるようにdocstringを関数に付けて置くことも必要になるでしょう。

docstringの書き方は、関数を定義してインデントしてコードブロックを書く時の先頭に、トリプルクォート（””” “””）で囲んで説明のドキュメントを記述します。