Python函数怎样给函数添加简单的注释说明 Python函数注释编写的基础方法教程-Python教程-PHP中文网

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

蓮花仙者

发布： 2025-08-18 22:49:01

原创

925人浏览过

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

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

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

解决方案

Python函数注释的核心在于

def

登录后复制

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

1. 参数注释 (Parameter Annotations)

直接在参数后面使用冒号

登录后复制

，然后写上注释。

立即学习“Python免费学习笔记（深入）”；

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

登录后复制

函数期望返回一个字符串。

即构数智人

即构数智人是由即构科技推出的AI虚拟数字人视频创作平台，支持数字人形象定制、短视频创作、数字人直播等。

查看详情

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 'str'>, 'greeting': <class 'str'>, 'return': <class 'str'>}

登录后复制