ARTICLE · 1331478

第22期|参数、返回值与说明文档

发布时间：2026-11-08 19:38:14 最近访问：2026-11-08 19:38:15

第22期|参数、返回值与说明文档

数智广西 · 技术专栏

第22期｜参数、返回值
与说明文档

Python 入门第四天（day04）· 数据容器与函数基础

本期关键词：形参 / 实参 · 参数顺序 · return · 多返回值封成元组 · docstring

Python 零基础函数约 15 分钟

本期导读

只会打分割线的函数没多大用。真正的函数是：喂给它数据（参数）→ 它算完 → 把结果交回来（返回值）。这一期讲透参数与返回值：形参与实参怎么对应、参数顺序错了会怎样、"返回多个值"到底变成了什么、return 之后还有没有代码在跑，最后给出写说明文档的标准姿势。

形参与实参

func_param.py（语法）

# 定义函数
def 函数名(形参列表):
函数体
......
return 返回值

# 调用函数
函数名(实参)

形参（形式参数）：
函数定义时括号里的参数，只能在函数内部使用（属于局部变量）。
实参（实际参数）：
函数实际调用时传进去的那个具体的值。

一个参数、一个返回值

函数：计算圆的面积（已知半径）。

func_circle.py

# 函数1: 计算圆的面积 -- 半径
def circle_area(r):
area = 3.14 * r ** 2
return area

area = circle_area(10) # 10 就是实参, 传给形参 r
print(area) # 314.0

两个参数

函数：计算长方形的面积（已知长、宽）。多个参数之间用逗号分隔。

func_rectangle.py

# 函数2: 计算长方形的面积 -- 长, 宽
def rectangle_area(l,w):
area = l * w
return area

print(rectangle_area(20, 10)) # 200 ---> 20 给 l, 10 给 w

参数顺序对不上会怎样

形参和实参是按位置一一对应的：第一个实参给第一个形参，第二个给第二个。顺序一对不上，结果就跟着错。用乘法看不出来（20 * 10 和 10 * 20 一样），换成减法立刻现原形：

param_order.py

# 第一个实参给 a, 第二个实参给 b
def calc(a, b):
return a - b

print(calc(10, 3)) # 7 正确
print(calc(3, 10)) # -7 顺序反了, 结果也反了

⚠️ 怎么避免
① 形参名字起得有区分度：rectangle_area(l, w) 比 rectangle_area(a, b) 更容易记。
② 调用时照着定义顺序念一遍：长度在前就给长度，宽度在前就给宽度。
③ 参数一多（四个以上），靠记位置必错——"关键字传参"是后面才讲的内容，现阶段把参数控制在两三个最稳。

返回多个值 → 装进元组

函数：一次算出圆的面积和周长。多个返回值之间用逗号分隔，Python 会把它们自动封装到一个元组（tuple）里。

func_multi_return.py

# 函数3: 计算圆的面积, 周长 -- 半径
# ----> 如果返回值有多个, 多个返回值之间逗号分隔 ---> 多个返回值会封装到元组之中
def circle_area_len(r):
returnround(3.14 * r * r, 1), round(2 * 3.14 * r, 1)

al = circle_area_len(10)
print(al) # (314.0, 62.8) ---> 是个元组
print(type(al)) # <class 'tuple'>

area, length = circle_area_len(10) # 解包
print(area) # 314.0
print(length) # 62.8

💡 又见解包
area, length = circle_area_len(10) 把返回的元组一次拆成两个变量——和 day03 的组包解包、第17期的 for k, v in ... 是同一套语法。这就是 Python 里"元组"最实用的场景之一。

🔔 三条注意
① 多个参数之间用逗号（,）分隔。
② return 只负责"返回"，不负责打印——想看到结果，要用 print() 输出。
③ 函数可以定义多个返回值，它们会被封装成一个元组。

给函数写说明文档

函数的说明文档（Docstring）是写在函数开头、用三个引号包裹的字符串，用来解释函数的功能、参数、返回值，方便调用者搞清楚细节。常用两个标记：

:param 参数名:
—— 描述函数的参数
:return:
—— 描述函数的返回值

func_docstring.py

# 函数2: 计算长方形的面积 -- 长, 宽
def rectangle_area(l,w):
"""
根据长方形的长度和宽度, 计算长方形的面积
:param l: 长度
:param w: 宽度
:return: 长方形的面积
"""
area = l * w
return area

print(rectangle_area(20, 10))
help(rectangle_area) # 查看函数的说明文档

怎么查看说明文档
· 方式一：用 help(函数名)，比如 help(rectangle_area)，控制台会打印出整段文档。
· 方式二：在 PyCharm 里鼠标悬浮在函数名上自动展示（推荐，最省事）。
记住：好的文档，能让你的代码更容易理解、使用和维护！

return 的两个细节

关于 return，有两个细节几乎每个人都会问一次：

return_detail.py

# 细节1: 没有 return, 函数返回 None
def out_line():
print("-" * 20)

result = out_line()
print(result) # None

# 细节2: return 之后的代码不会执行
def test():
return1
print("这行永远不会执行")

print(test()) # 1 ---> 只返回, 不打印

两个细节各自的意思
① 没写 return（或只写 return 不带值）→ 默认返回 None。所以函数"看起来什么都没交出来"，不是它坏了，是它本来就只干了打印这件事。
② return 一执行，函数立刻结束，它下面的代码属于"写了但永远跑不到"，Python 不会报错，但你可以自己删掉。

🔍 排错口诀
函数"没反应"时，按这个顺序查：① 有没有调用（带括号）→ ② 函数里有没有 print → ③ 有没有 return 并用变量接住。三步走完，九成问题当场定位。

✓