プログラムは文章と同じで、「読み易さ」が求められます。相手が読めない以前に、３日も経てば自分すら理解できない。そんなプログラムでは、手直しするにも一苦労です。
プログラムの理解に不可欠なのが、コメントです。コードだけでは理解に苦しむプログラムも、コメントの説明があれば分かり易くなります。
適切にコードに説明を加えることは、読み易さだけでなく、コードの価値まで左右します。コメントは最も汎用的な方法ですが、今回は関数の説明に便利な「関数アノテーション」を取り上げます。
関数は独立したユニットとして再利用されるので、「目的（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の２つを引数として用いて、文字列（str）を呼び出し側に返すことを示しています。
つまり、関数を定義している以下のdefの節を見ただけで、何を材料（引数）に、どんな成果（戻り値）が得られるかがわかるのです。
def add_honor(name:str, is_female:bool) -> str:なお、デフォルトの引数値を指定する場合は、以下のように期待する型を示した後に記述します。
def add_honor(name:str, is_female:bool = True) -> str:関数アノテーションを使う際に考慮すること
使用に際しては、以下の３点を考慮してください。
- Python3でサポートされている（Python2では使えない）。
- オプションなので、使わなくても問題ない。
- 単に期待する情報なので、従わなくてもエラーにならない（型チェックはしない）。
特に留意すべきは、３つめです。関数アノテーションはあくまで期待する型を記述するだけであり、型を強制するものではありません。Pythonは引数の型や関数が返す型には、全く関与しません。
関数アノテーションを使うメリット
第一のメリットは、関数の使用方法がひと目でわかることですが、PyCharmを使用しているとさらなる恩恵が得られます。
関数アノテーションで引数の型を記述しておけば、PyCharmがその引数の型を認識してコード補完（Code completion）を有効にしてくれるのです。
例えば、以下のset_axies関数の引数axは、matplotlibのAxesクラスであると明記してあるので、メソッドをコード補完で入力できます。これは、コーディングする際に、非常に助かります。
最後に
関数アノテーションは、要するに標準化されたドキュメンテーションです。付け加えれば、コードがぐっと分かり易くなります。これから書くコードはPython3を用いると思いますので、積極的に利用することを強くオススメします。
なお、さらに詳しい情報は英語になってしまいますが、以下のPEP3107を参考にしてください。