プログラムは文章と同じで、「読み易さ」が求められます。相手が読めない以前に、3日も経てば自分すら理解できない。そんなプログラムでは、手直しするにも一苦労です。

プログラムの理解に不可欠なのが、コメントです。コードだけでは理解に苦しむプログラムも、コメントの説明があれば分かり易くなります。

適切にコードに説明を加えることは、読み易さだけでなく、コードの価値まで左右します。コメントは最も汎用的な方法ですが、今回は関数の説明に便利な「関数アノテーション」を取り上げます。

関数は独立したユニットとして再利用されるので、「目的(docstringに書かれる)」だけでなく、「使用方法」がひと目でわかると助かります。関数アノテーションは、引数と戻り値の型注記(アノテーション)で記述することで、ひと目で使用方法がわかるようにします。

関数アノテーションの書き方

関数アノテーションの構文は単純です。以下の要領で記述するだけです。

  • 関数の引数に期待する型は、引数の後に、コロン:を付けて示す。
  • 戻り値に期待する型は、引数の閉じカッコの後に、矢印->を付けて示す。

実際のコード例で見てみましょう。

def add_honor(name:str, is_female:bool) -> str:
    """名前に敬称を付ける。"""
    if is_female:
        return "Ms. " + name
    else:
        return "Mr. " + name

name_title = add_honor("Yamaguchi", True)
print(name_title)
# Ms. Yamaguchi

add_honor関数は、文字列(str)のname、ブール(bool)のis_femaleの2つを引数として用いて、文字列(str)を呼び出し側に返すことを示しています。

つまり、関数を定義している以下のdefの節を見ただけで、何を材料(引数)に、どんな成果(戻り値)が得られるかがわかるのです。

def add_honor(name:str, is_female:bool) -> str:

なお、デフォルトの引数値を指定する場合は、以下のように期待する型を示した後に記述します。

def add_honor(name:str, is_female:bool = True) -> str:

関数アノテーションを使う際に考慮すること

使用に際しては、以下の3点を考慮してください。

  1. Python3でサポートされている(Python2では使えない)。
  2. オプションなので、使わなくても問題ない
  3. 単に期待する情報なので、従わなくてもエラーにならない(型チェックはしない)。

特に留意すべきは、3つめです。関数アノテーションはあくまで期待する型を記述するだけであり、型を強制するものではありません。Pythonは引数の型や関数が返す型には、全く関与しません。

関数アノテーションを使うメリット

第一のメリットは、関数の使用方法がひと目でわかることですが、PyCharmを使用しているとさらなる恩恵が得られます。

関数アノテーションで引数の型を記述しておけば、PyCharmがその引数の型を認識してコード補完(Code completion)を有効にしてくれるのです。

例えば、以下のset_axies関数の引数axは、matplotlibのAxesクラスであると明記してあるので、メソッドをコード補完で入力できます。これは、コーディングする際に、非常に助かります

pycharm function annotations

最後に

関数アノテーションは、要するに標準化されたドキュメンテーションです。付け加えれば、コードがぐっと分かり易くなります。これから書くコードはPython3を用いると思いますので、積極的に利用することを強くオススメします

なお、さらに詳しい情報は英語になってしまいますが、以下のPEP3107を参考にしてください。

PEP 3107 — Function Annotations