函数签名应清晰表达用途、输入输出和边界条件，通过类型提示、描述性参数名、/和*分隔符、合理布尔命名及精准docstring提升可读性与健壮性。
函数签名是代码的“第一张脸”，清晰的签名能让人一眼看懂函数用途、输入输出和边界条件。Python 提供了类型提示、默认值、关键字限定、文档字符串等机制，合理组合它们就能大幅提升可读性。
用明确的参数名 + 类型提示说明“是什么”
避免模糊缩写（如 def calc(x, y, z)），改用描述性名称并标注类型：
- def calculate_discounted_price(original_price: float, discount_rate: float, tax_rate: float = 0.08) -> float:
- 类型提示让 IDE 能校验传参，也省去读者翻文档查“x 是不是价格”
- 基础类型（
int,str,list[str]）直接写；复杂结构可用typing.NamedTuple或dataclass封装后作为类型名，提升语义
把可选逻辑显式分离，避免“一参数多含义”
不要用一个布尔参数控制多个行为（如 def process(data, verbose=False, debug=False, dry_run=False)），它会让调用时难以判断意图：
- 优先拆成独立函数： process(data)、process_with_logging(data)、simulate_process(data)
- 若必须保留单入口，用
**kwargs或专用配置对象（如ProcessingOptions）集中管理，再在函数内做语义校验 - 对布尔参数，命名要带正向动词（skip_validation 比 no_check 更易理解）
用 / 和 * 强制调用方式，减少误用可能
位置参数（/ 前）和关键字参数（* 后）的分隔，能约束调用习惯，让接口更稳定：
立即学习“Python免费学习笔记（深入）”；
-
def format_date(year: int, month: int, day: int, /, style: str = "iso") -> str: —— 年月日必须按序传位置参数，防止
format_date(style="us", year=2024, ...)这类易错写法 - def send_email(*, to: str, subject: str, body: str) -> bool: —— 强制使用关键字调用，调用时一眼看清每个参数含义，不依赖顺序
- 这种语法从 Python 3.8 支持，适合新项目或关键函数逐步引入
配一句精准的 docstring，补全“为什么”和“注意什么”
类型提示说明“是什么”，docstring 要说明“为什么这样设计”和“边界怎么处理”：
- 用 Google 或 NumPy 风格（非 reStructuredText），简洁直白。例如：
def clamp(value: float, min_val: float, max_val: float) -> float: """限制 value 在 [min_val, max_val] 区间内，超出则截断。 注意：若 min_val > max_val，行为未定义，调用前请确保 min_val <= max_val。 """- 重点写约束、副作用、常见错误、特殊返回值（如 None 表示未找到），而不是重复参数名
