Python函数注释写法详解

想让你的Python代码更清晰易懂、更方便协作吗？本文为你详细解读Python函数注释的写法，堪称基础教程详解！函数注释就像是给函数添加了一份说明书，通过参数注释、返回值注释和Docstrings，清晰地描述函数的功能、输入输出，极大地提升代码可读性和团队协作效率。更重要的是，函数注释还能被mypy等工具利用，进行类型检查，以及被Sphinx等文档生成工具解析，自动生成API文档。掌握Python函数注释，让你的代码更规范、更专业！本文将深入讲解参数注释、返回值注释和Docstrings的使用方法，并介绍如何查看函数注释，以及函数注释的使用场景和注意事项，助你轻松掌握这一实用技巧。

函数注释通过参数注释、返回值注释和Docstrings为函数提供说明，提升可读性与协作效率，支持工具进行类型检查和文档生成，但不强制运行时类型检查。

函数注释，简单来说，就是给你的Python函数加上说明书。它能让别人（也包括未来的你）更快理解这个函数是干嘛的，输入是什么，输出又是什么。但要注意，这不仅仅是写给人的，一些工具也能利用这些注释做类型检查、文档生成等等。

解决方案

Python函数注释的核心在于 def 语句后，参数列表的括号内，以及函数体内的特定位置。主要有两种方式：参数注释和返回值注释。

1. 参数注释 (Parameter Annotations)

直接在参数后面使用冒号 :，然后写上注释。

def greet(name: str, greeting: str = "Hello") -> str:
  """
  问候某人。

  Args:
    name: 被问候者的名字。必须是字符串。
    greeting: 问候语。默认为 "Hello"。

  Returns:
    包含问候语的消息。
  """
  return f"{greeting}, {name}!"

print(greet("Alice"))
print(greet("Bob", "Good morning"))

这里，name: str 表示 name 参数期望是一个字符串。greeting: str = "Hello" 表示 greeting 参数也是字符串，并且有一个默认值 "Hello"。 注意，这些注释不会强制类型检查，Python仍然是动态类型语言。

2. 返回值注释 (Return Annotations)

在参数列表的括号后，使用箭头 ->，然后写上返回值的注释。

在上面的例子中，-> str 表示 greet 函数期望返回一个字符串。

3. Docstrings (文档字符串)

虽然不是严格意义上的“注释”，但 Docstrings 在函数中起着至关重要的说明作用，通常用三重引号 """Docstring goes here""" 包裹。 Docstrings 应该清晰地描述函数的功能、参数、返回值，以及任何可能引发的异常。许多文档生成工具（如 Sphinx）会解析 Docstrings 来自动生成文档。

4. 组合使用

可以同时使用参数注释、返回值注释和 Docstrings，以提供最全面的函数说明。

def calculate_area(width: float, height: float) -> float:
  """
  计算矩形的面积。

  Args:
    width: 矩形的宽度，必须是浮点数。
    height: 矩形的高度，必须是浮点数。

  Returns:
    矩形的面积，浮点数。
  """
  return width * height

如何查看函数注释？

可以通过 help() 函数或者 __annotations__ 属性来查看函数的注释。

help(greet) # 显示 greet 函数的 Docstring 和签名信息
print(greet.__annotations__) # 输出: {'name': , 'greeting': , 'return': }

什么时候应该使用函数注释？

• 提高代码可读性： 当函数功能复杂或者参数较多时，注释能帮助理解代码意图。
• 方便团队协作： 团队成员可以通过注释快速了解函数的使用方法。
• 利用工具进行类型检查： 可以使用像 mypy 这样的工具来静态检查代码中的类型错误。
• 生成文档： Docstrings 可以被文档生成工具解析，自动生成 API 文档。

函数注释对性能有影响吗？

函数注释本身对Python代码的运行时性能几乎没有影响。因为Python解释器在运行时会忽略这些注释，除非你显式地去访问它们（例如通过__annotations__属性）。

函数注释可以代替类型检查吗？

不可以完全代替。Python仍然是动态类型语言，即使你添加了类型注释，Python解释器在运行时也不会强制执行类型检查。但是，类型注释可以被静态类型检查工具（如mypy）使用，在不运行代码的情况下发现潜在的类型错误。这有助于在开发阶段及早发现问题，提高代码质量。可以将函数注释看作是类型检查的一种补充手段，而不是替代品。

以上就是《Python函数注释写法详解》的详细内容，更多关于Python,函数注释,代码可读性,类型检查,Docstrings的资料请关注golang学习网公众号！