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

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

蓮花仙者

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

原创

933人浏览过

函数注释通过参数注释、返回值注释和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

登录后复制

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

ghiblitattoo

用AI创造独特的吉卜力纹身

175

查看详情

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'>}

登录后复制