答案。

问题历史

在Python的早期版本中，就鼓励通过docstring来记录代码。自Python 3.5（PEP 484）推出后，添加了类型注释（type hints）以提高可读性，并改善类型分析器（例如mypy，pyright等）的支持。因此，可以在函数和类的定义中结合文档和类型注释。

问题

没有类型注释，难以快速理解函数的操作及其预期结果。缺乏良好的docstring会导致接口理解不当和使用错误。如果错误地使用类型提示或docstring，会干扰静态分析并降低代码支持。

解决方案

使用多行docstring记录函数的目的、参数和结果，以及使用类型提示明确指明参数类型和返回值类型。

代码示例：

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: ...注释而不是类型注释吗？这有什么必要？

可以，如果需要兼容Python 2或旧代码库。例如：

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

mypy和类似工具会将其视为现代语法，但在新项目中最好使用标准类型注释。

常见错误和反模式

公共函数和类缺少docstring或docstring为空
类型指定错误——例如，使用List而不是list或类型中的拼写错误（特别是在复杂集合中）
在不更新文档的情况下使用类型提示，反之亦然

生活示例

负面案例

在大型项目中，函数根本没有docstring和类型提示——开发者花费大量时间来学习和调试，常常在参数类型和输入数据的目的上出错。

优点：

启动时快速编写代码

缺点：

难以维护，新员工的入职时间大大延长
如果参数类型错误，很难捕获错误。

正面案例

所有公共函数都有详细的docstring和正确的类型提示，使得IDE和分析器能够快速发现类型错误并自动生成API文档。