1. 命名原则的框架
1.1 语义性、可读性与简洁性的平衡
语义性是函数命名的核心，名字应清晰表达函数的目标与行为，避免让后续维护者猜测其用途。
可读性要求命名符合自然语言习惯，避免生僻缩写，确保团队成员在不查看实现细节的情况下也能理解。
简洁性并不等于简短，而是在不过度冗长的前提下，传达准确信息。过长的名称会降低可读性，过短的名称又可能造成歧义。
# 不推荐：语义模糊且可读性差
def proc(x):pass# 推荐：清晰表达意图且可读性强
def calculate_total_price(items, tax_rate):"""计算商品清单的总价并应用税率"""subtotal = sum(item['price'] * item['qty'] for item in items)return subtotal * (1 + tax_rate)
1.2 一致性原则在模块与包中的应用
在同一模块或包内，使用统一的命名风格可以显著提升代码的可维护性与导航效率。
为相同领域的操作建立统一前缀或后缀，例如对“用户相关”操作采用 user_
命名空间的一致性有助于减少跨模块的认知成本，保持同类函数在不同文件中的风格一致。
# 模块 user.py 内的统一命名
def create_user(username: str, email: str) -> dict:...def delete_user(user_id: int) -> None:...def update_user(user_id: int, data: dict) -> dict:...
2. 实战要点与模式
2.1 函数签名的设计要点
函数签名应清晰地表达输入、输出以及副作用，便于静态分析与单元测试。
在参数设计上，优先使用显式的命名参数而非大量位置参数，必要时使用类型提示提高可推断性。
函数签名应具备自文档性，只要读名字就能大致理解功能，不一定需要立即查看实现。
def process_order(order_id: int, *, include_tax: bool = True) -> dict:"""处理一个订单并返回处理结果字典，可选择是否包含税费。# 不推荐：参数含义不明确
def process(o, t=False):pass# 推荐：签名自解释且可测试
def process_order(order_id: int, *, include_tax: bool = True) -> dict:pass
2.2 私有化与暴露接口的命名约定
公开接口应以无前缀的函数名存在，以便直接暴露给外部使用者；私有实现应以下划线开头，提醒开发者这是内部实现细节。
使用明确的私有前缀可以降低误用风险，同时为未来的重构留出空间。
暴露接口的命名要简洁且描述性，私有实现要标注清晰的边界。
# 公共接口
def render_dashboard(data: dict) -> str:...# 私有实现（内部使用，不对外暴露）
def _format_dashboard(data: dict) -> str:...
# 不推荐：私有与公开混乱
def _render(data: dict) -> str:...def render(data: dict) -> str:...# 推荐：清晰分离
def render_dashboard(data: dict) -> str:...def _sanitize_dashboard_input(data: dict) -> dict:...
