Pythonコードのdocstringや型アノテーションについて

さぼりがちな自分のコード

近年Pythonでは型アノテーションを付けていこう的な流れになっているようです。個人的にはそこまでやるんだったら「がっつり型を指定する言語を使うほうがいいじゃない」という気持ちを持ちつつ、一応勉強しておりました。

ですので、一度しっかりとしたdocstringおよび型アノテーションを書いてみようと、現在私がGitHubのmy-python-warehouseというリポジトリに置いているコードから書き直して行くことにしました。

docstring

まずdocstringのスタイルについてですが、なにやらNumpyスタイル、Googleスタイルといった流派があるようで、私はGoogleスタイルが読みやすそうかなと思い、そちらにしました。

Pythonのdocstringおよび型アノテーションを書いたコードは以下のようになります。（例：my-python-warehouse/greeting.py）


from typing import Optional

def hello(name: Optional[str] = None) -> str:
    """Hello world program
    Args:
        name (:obj: `str`, optional)
    Returns:
        str
    Raises:
        TypeError: If name is not str, raise this.
    Examples:
        >>> hello()
        'Hello, world!!'
        >>> hello("Tom")
        'Hello, Tom!!'
        >>> hello(123)
        Traceback (most recent call last):
            ...
        TypeError: Not string
    """
    if name is None:
        return hello("world")
    else:
        if not isinstance(name, str):
            raise TypeError("Not string")
        else:
            return f"Hello, {name}!!"

if __name__ == '__main__':
    import doctest
    doctest.testmod()

docstringを表示するには以下のようにします。


>>> import greeting
>>> print(greeting.hello.__doc__)
Hello world program
    Args:
        name (:obj: `str`, optional)
    Returns:
        str
    Raises:
        TypeError: If name is not str, raise this.
    Examples:
        >>> hello()
        'Hello, world!!'
        >>> hello("Tom")
        'Hello, Tom!!'
        >>> hello(123)
        Traceback (most recent call last):
            ...
        TypeError: Not string

単純なプログラムで恐縮ですが、ちゃんと書くと、確かにどういう関数なのかがわかりやすくなりますね。ちなみにExamplesのコードはdoctestモジュールでテストできます。Tracebackのところに...と書いていますが、これは実際にこのまま書いて問題ありません。

やってみての感想

実際やってみて、これらは単純なコードに関してはさほどメリットを感じないですが、チームでの開発・中・大規模な開発になってくると大きなメリットとなってくるのだろうなと感じました。個人で中規模のプロジェクトを作成する場合にも、時間とともに記憶があいまいになり、「なんの関数だったっけ？」なんてことになっても、作成時にdocstringや型アノテーションを追加しておけば、きっと助けになることでしょう。特に脳みその引き出しが開きにくくなっている私には必須のものなのかもしれません。ただ、型アノテーションのなんとなくフワッとした感じ（ガチガチに型指定したわけではないという）はやはりモヤっとします。書く量と労力に本当に見合うものなのか？皆さんはどのようにお感じになりますでしょうか？

2021/11/10