Python函数怎样给函数添加简单的注释说明 Python函数注释编写的基础方法教程​

函数注释通过参数注释、返回值注释和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': <class>, 'greeting': <class>, 'return': <class>}</class></class></class>

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

• 提高代码可读性： 当函数功能复杂或者参数较多时，注释能帮助理解代码意图。
• 方便团队协作： 团队成员可以通过注释快速了解函数的使用方法。
• 利用工具进行类型检查： 可以使用像

  mypy

  这样的工具来静态检查代码中的类型错误。
• 生成文档： Docstrings 可以被文档生成工具解析，自动生成 API 文档。

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

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

__annotations__

属性）。

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

不可以完全代替。Python仍然是动态类型语言，即使你添加了类型注释，Python解释器在运行时也不会强制执行类型检查。但是，类型注释可以被静态类型检查工具（如

mypy

）使用，在不运行代码的情况下发现潜在的类型错误。这有助于在开发阶段及早发现问题，提高代码质量。可以将函数注释看作是类型检查的一种补充手段，而不是替代品。

Python免费学习笔记（深入）：立即学习
在学习笔记中，你将探索 Python 的核心概念和高级技巧！