函数参数命名应直述其本质，用完整名词、避免缩写，类型线索融入名称；默认值须具业务意义，慎用函数调用；类型提示需准确简洁；参数顺序遵循“数据→行为→控制”，必要时强制关键字。
函数参数命名要直说“它是什么”，别玩缩写或代号
用户调用函数时，第一眼看到的是参数名。如果写成 def process_data(src, dst, cfg)，没人能立刻判断 src 是路径、URL 还是字节流，cfg 是字典、对象还是文件路径。这种命名把理解成本甩给了调用方。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用完整名词：用
input_path代替src，用output_format代替fmt - 动词前缀慎用：避免
is_valid这类布尔参数——它暗示返回值语义，但参数本身只是开关；更中性的是validate_input - 类型线索可融入名称：如
timeout_seconds比timeout更明确，尤其当 Python 类型提示缺失或未被 IDE 充分识别时
默认值不是“随便填个数”，而是表达设计意图
设 def load_config(path="config.yaml") 看似方便，但如果多数场景下用户必须传参，这个默认值反而制造干扰——它暗示“不传也行”，实际却可能触发错误配置加载。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 只对真正有业务意义的默认行为设值：比如
retry_delay=1.0表示“重试间隔默认 1 秒”是合理约定；而cache=None作为占位符就比硬设cache={}更诚实 - 用
None作哨兵值，配合文档说明“不传则禁用某功能”，比用魔法数字（如max_retries=-1）更易维护 - 避免在默认值里调用函数（如
default=datetime.now()）——它会在定义时求值，所有调用共享同一时间点
类型提示不是装饰，是签名的一部分
没类型提示的 def parse(text)，和带提示的 def parse(text: str) -> dict[str, Any]，对 IDE 补全、mypy 检查、甚至阅读者推断行为，差距巨大。但类型提示写错比不写更危险。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 基础类型优先：用
str、int、list[str]，别一上来就上Union或自定义Protocol——除非接口确实需要多态 - 可选参数统一用
Optional[T]，而不是T | None（Python 3.10+ 虽支持，但部分旧工具链解析不稳定） - 函数本身作为参数时，明确写出签名：
transform: Callable[[str], int]，比模糊的transform: callable有用得多
参数顺序暴露调用逻辑优先级
Python 不支持命名参数强制，所以位置参数顺序直接影响使用体验。把最核心、最常变的参数放前面，把修饰性、低频参数往后排，能让调用更自然。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 遵循“数据 → 行为 → 控制”的隐含节奏：比如
def send_email(to: str, subject: str, body: str, cc: list[str] | None = None, timeout: float = 30.0)—— 收件人、主题、正文是必填主干，抄送和超时是可选控制项 - 避免把布尔开关放在中间：像
def render(template, debug=False, context)会迫使用户写render(tpl, False, ctx)，破坏可读性；改用关键字参数或调整顺序 - 必要时用
*强制关键字参数：如def connect(host, port, *, ssl=True, timeout=None)，防止未来新增参数破坏兼容性
函数签名不是语法容器，是接口契约的第一行文字。一个让人犹豫要不要点进源码看参数含义的函数，大概率会在三个月后被绕开重写。
