プログラミングのネタ帳

30代からプログラミングをはじめた。記憶力が悪いのでメモ代わりに。

pythonのdocstring機能を使って関数の仕様を書く・確認する

少しずつ読み進めているオライリーの実践Cプログラミングでは、コメントを書くこと、

例えば、変数名に関して、

・意味のある名前にして、極力省略しない。

・宣言は1つにつき1行使う。コメントをつけて、単位を書いておくのが好ましい

という風に徹底しています。

関数に関しても、

・引数、戻り値をきちんと明示する(型、等々)

ということが書いてあった気がします。

 

そこで表題、pythonではdocstringという関数の仕様を自分で記入できる機能があり、また標準関数についてもその仕様を確認することができます。

また、標準関数についてもdocstingを参照し使い方を知ることができます。

docstringの表示は、以下の通り、特殊メソッド__doc__、またはhelp関数を使う方法があります。

・funcname.__doc__

・help(funcname)


print(list.insert.__doc__)
print(help(list.insert))
実行結果
Insert object before index.

Help on method_descriptor:

insert(self, index, object, /)
    Insert object before index.

print関数を使っていますし、行が少ないので分からないですが、インタラクティブでは__doc__は改行せずに表示されます。 help関数は整えて表示します。

自作の関数にdocstringを記述するには、関数名の下の行に""" """ と囲むことで実装出来ます。 書き方は色々あると思います。以下の例では関数の機能。引数。戻り値・例外処理・使用例を書いています。


def mydivision(a,b):
    """
    関数名 mydivision(a,b)
    機能
        第一引数を分子 第二引数を分母として
        割り算を計算し答えを返す
    引数 (float a,float b)
     float a 分子
     float b 分母
    戻り値 float: 1/b
    例外 b=0であればzerodivisionerrorとして検出しsys.exit()する
    例 myadd(10,2)
    """
    a,b=float(a),float(b)
    try:
        return a/b
    except ZeroDivisionError as e:
        print(e,"第二引数は分母で、0を代入しています")
        sys.exit()

help(mydivision)とすれば、以下が表示されます


Help on function mydivision in module __main__:

mydivision(a, b)
    関数名 mydivision(a,b)
    機能
        第一引数を分子 第二引数を分母として
        割り算を計算し答えを返す
    引数 (float a,float b)
    戻り値 float: 1/b
    例外 b=0であればzerodivisionerrorとして検出しsys.exit()する
    例 myadd(10,2)

関数の使い方を忘れたのなら、ググるよりもまず関数のdocstringを確認する癖をつけた方がいいかもしれないと最近思っています。