函数参数设计应明确意图、控制数量、规范命名：用类型提示提升可读性，区分必需/可选/关键字专用参数，慎用args/*kwargs，优先采用dataclass封装复杂配置，布尔参数加is_/has_前缀，参数数建议≤5。
明确参数意图，用好类型提示和默认值
函数参数不是越少越好，也不是越多越灵活，关键是让调用者一眼看懂“该传什么、为什么传”。Python 3.5+ 支持 类型提示，它不强制运行时检查，但极大提升可读性和 IDE 支持：
- 基础类型直接写，如
name: str、count: int； - 可选参数用
Optional[str]或str | None（Python 3.10+）； - 容器类型写清楚元素类型，如
items: list[dict[str, Any]]； - 默认值应是不可变对象（
None、数字、字符串），避免用[]或{}做默认值，防止状态污染。
区分必需参数、可选参数与关键字专用参数
按调用语义分层设计参数位置，能减少误用：
-
必需位置参数：核心输入，如
def download(url: str, timeout: float)中的url； -
带默认值的可选参数：配置类选项，如
timeout: float = 30.0； -
关键字专用参数（*）之后：强制命名，避免调用时顺序错乱，适合多配置项，例如：
def render(template: str, data: dict, *, indent: int = 2, skip_empty: bool = False)
这样调用必须写render("t.html", {}, indent=4, skip_empty=True)，不能省略参数名。
合理使用 *args 和 **kwargs，但别滥用
它们适合“透传”或高度泛化场景，不是掩盖设计缺陷的补丁：
-
*args适合处理同质不定长序列，如def sum_all(*numbers: float) -> float:； -
**kwargs适合接收下游函数的配置（如requests.get(url, **req_kwargs)），或实现插件式扩展； - 避免写
def func(*args, **kwargs)却不说明接受哪些参数——这等于放弃接口契约； - 如果发现频繁需要加新参数，优先考虑重构为数据类（
dataclass）或配置对象，而非堆砌**kwargs。
命名清晰，避免缩写和模糊词
参数名是函数文档的第一行。差的名字会让调用者反复查源码：
立即学习“Python免费学习笔记（深入）”；
- 用
user_id: str而不是uid: str（除非团队强约定）； - 用
is_active: bool而不是active: bool（布尔值前缀is_/has_/can_更直观）； - 避免
flag、data、info这类无信息量的名称； - 当一个参数有多个合法取值时，考虑用
Literal或枚举（Enum）约束，如mode: Literal["fast", "safe", "debug"]。
函数职责单一，参数数量建议控制在 5 个以内
超过 5 个参数往往意味着函数在做太多事，或缺少中间抽象：
- 若参数常成组出现（如
host、port、username、password），提取为连接配置类； - 用
@dataclass定义配置对象，既清晰又支持默认值和类型提示； - 实在无法精简时，至少把后几个参数设为关键字专用（
*后），强制调用者注明意图，降低出错概率。
