何週間後とかに見ても、この関数何やってんの？って思い出せない時

関数の最初にコメントを入れたり、引数にも説明を入れれるのでその使い方と見方

作ったサンプル：https://github.com/KodairaTomonori/Qiita/blob/master/default_module/syntax/function.py

※ knoguchiさんの指摘があり、修正させていただきました(2015/10/28)。

例：単純な足し算のプログラム

comennt.py

def addition(num_a: int, num_b: int, flag:bool=True) -> int:
    '''
        この関数は、num_a + num_bを計算して返すプログラムです。
        flagをTrueにすると結果を見やすくprintしてくれます。
    '''
    if flag: print('{} + {} = {}'.format(num_a, num_b, num_a + num_b) )
    return num_a + num_b

if __name__ == '__main__':
    result = addition(1234, 4321)
    print('result:', result) 
    print('引数の情報: ', addition.__annotations__)
    print('関数の説明: ', addition.__doc__)

出力

output.txt

1234 + 4321 = 5555
result: 5555
引数の情報:  {'num_b': <class 'int'>, 'num_a': <class 'int'>, 'return': <class 'int'>, 'flag': <class 'bool'>}
関数の説明:  
        この関数は、num_a + num_bを計算して返すプログラムです。
        flagをTrueにすると結果を見やすくprintしてくれます。

解説

addition関数自体は、簡単な足し算をしてくれるプログラムで、flagをFalseにすると結果だけを返してくれます。

関数に説明を入れる

引数に説明を入れたい時は、
(num_a: int, num_b: int, flag:bool=True) -> int
辞書みたいに書いていきます。左に引数名、右に型(引数:型)そして、デフォルト値を与えたい時は、後ろに=Trueのように加えるだけです。
最後に、-> intで、返り値の型も入れることができます。

この、引数の説明の参照の仕方は、addition.__annotations__とすることで、見ることができます。

関数に説明文を入れる時は、defで宣言した次のところで文字列を入れることでできます。
この説明文の参照の仕方は、addition.__doc__とすることで、見ることができます。

まとめ

引数名をしっかり後で見てもわかりやすくすることも重要ですが、説明文を入れることでもっとわかりやすくなるので、これからは面倒くさがらず書こうと思います。