回答。

問題の歴史

Pythonでは、最初のバージョンからコードのドキュメント化がdocstringを通じて奨励されています。Python 3.5の登場（PEP 484）により、型アノテーション（type hints）が追加され、可読性が向上し、タイプチェッカー（例えば、mypy、pyrightなど）のサポートが改善されました。これにより、関数やクラスの定義に文書と型付けを直接組み合わせることができます。

問題

型アノテーションがないと、関数が何を扱っているのか、何を期待できるのかを迅速に理解するのが難しくなります。良好なdocstringが不足すると、インターフェースの誤解や使用エラーが発生します。type hintsやdocstringsを不適切に使用すると、静的解析が妨げられ、コードのサポートが低下します。

解決策

関数の目的、パラメータ、および結果を文書化するためにマルチラインのdocstringを使用し、引数と戻り値の型を明示的に指定するためにtype hintsを使用します。

コード例:

def add_numbers(a: int, b: int) -> int:
    """
    ２つの整数を加算し、その結果を返します。

    :param a: 最初の加算数, int
    :param b: ２番目の加算数, int
    :return: 合計, int
    """
    return a + b

主な特徴:

Docstringは__doc__に保存され、IDE、help()、自動生成ドキュメントのために利用可能です
型アノテーションは__annotations__を通じてアクセス可能; コードの実行には影響しませんが、分析のためにのみ使用されます
統合使用は大規模なサポートと新しいプログラマーのオンボーディングを容易にします

ひっかけ質問。

型アノテーションはプログラムの実行に影響を与えることがありますか？

いいえ。型アノテーション（type hints）は、実行中にPythonインタープリターによってチェックされることはなく、分析ツールやIDE、ドキュメントの自動生成のためだけに使用されます。これらは実行時エラーを引き起こすことはなく、常にオプショナルです。

型アノテーションを使用してパラメータの値を制限することはできますか？

いいえ。例えば、x: intと指定しても、実際には他の型の値を渡すことを禁止するものではありません。実行時チェック（assert/isinstance）を使用することはできますが、type hintsは自動的に検証されません。

型アノテーションの代わりにコメント# type: ...を使用できますか？それはどのような場合に必要ですか？

はい、Python 2との互換性や古いコードベースを考慮する必要がある場合に許可されます。例えば:

def foo(x, y):     # type: (int, str) -> bool
    pass

これはmypyや同様のツールで現代の構文と同じように理解されますが、新しいプロジェクトでは標準のアノテーションを使用する方が良いです。

一般的なエラーとアンチパターン

公開関数やクラスにdocstringがないか、空のdocstring
誤った型指定 — 例えば、Listの代わりにlistや、型のスペルミス（特に複雑なコレクションで）
ドキュメントを更新せずにtype hintsを使用したり、その逆を行ったりすること

実生活の例

ネガティブケース

大規模なプロジェクトで関数には全くdocstringやtype hintsが付いておらず、開発者は学習やデバッグに多くの時間を費やし、しばしば型や引数の目的を間違えます。

利点:

スタート時のコード作成が迅速

欠点:

保守が非常に困難で、新しい社員のオンボーディングが大幅に遅れる
引数の型が混同されるとエラーの特定が難しい

ポジティブケース

すべての公開関数には詳細なdocstringと正確なtype hintsがあり、これによりIDEや解析ツールが迅速に型エラーを見つけ、API用のドキュメントを自動的に生成できます。