ドキュメンテーション文字列について

今回の記事では、ドキュメンテーション文字列について取り扱っていきます。

ドキュメンテーション文字列を一言でいうと、

関数の説明文

です。

前回までの記事で関数の取り扱い方を説明したと思いますが、関数やその引数を定義するときに、引数が特定のデータ型でないと作動しないことがよくあります。また、関数の動作を確認するときにいちいち関数のコードを読むことは面倒です。そのため、関数を呼び出す人に引数のデータ型や関数の動作について伝える方法が必要になってきます。そのために用いられるのがドキュメンテーション文字列であり、docstringと書かれます。実際に具体例で確認してみましょう。ドキュメンテーション文字列は、関数定義の直後に三重引用符'''を用いることで書くことができます。また、ドキュメンテーション文字列はhelp関数を用いれば参照することができます。

テキストエディタ　docstring.py

def multiplication(x,y):
   """

   Return x * y
   :param x: int
   :param y: int
   :return: int multiplication of x and y
   """
   return x * y
print(multiplication(5,6))

print(help(multiplication))

これを実行すると以下のようになります。

コマンドライン

python3 docstring.py

30

Help on function multiplication in module __main__:

  Return x * y
   :param x: int
   :param y: int
   :return: int multiplication of x and y
   """
   return x * y

None

以上のように、ドキュメンテーション文字列を使うと、help関数を用いてドキュメンテーション文字列の内容を参照することができます。ドキュメンテーション文字列は、誰が読んでも関数の機能や引数の定義が分かるように書けばよいですが、基本的には次のように書きます。

最初の行で、関数の役割を説明する。

次の行で、引数の型を説明する。paramは英語で引数という意味です。

最後に関数が返す値を説明する。

このようにドキュメンテーション文字列を書けば、他の人がその関数を用いるときにコードを読まなくて済むので、とても楽になりますよね。以上で今回の記事は終わりです。お疲れさまでした。