python-guidelines

Python 指南

集成到现有代码中。不要在后面追加代码。

简单胜于复杂。扁平胜于嵌套。 错误绝不能悄无声息地被忽略，除非明确将其静默处理。 如果实现难以解释，那它就是个糟糕的主意。

-- Python 之禅（PEP 20）

代码理念

• 遵循现有的命名、导入和签名模式。使用已有的工具函数和数据结构。
• 函数只负责一个目的。不要硬编码会降低通用性的行为。
• 不要为 2 行或更少的代码编写无意义的包装函数，直接内联。
• 在单次使用的位置内联变量。
• 除非情况至关重要，否则不要使用 try/except。让错误显现出来。
• 不要重复代码。
• 函数自行处理输入验证。不要在主逻辑中使用 if-else 检查。
• 使用 pathlib，而不是 os.path。
• 考虑 MongoDB/Gemini/OpenAI/Claude/Voyage 的 API 和时间成本。

不要这样做：

# Generate comment report only if requested
if include_comments:
    comment_report = generate_comments_report(start_date, end_date, team, verbose)
else:
    comment_report = ""
    print("   Skipping comment analysis (disabled)")

应该这样做：

comment_report = generate_comments_report(start_date, end_date, team, verbose) if include_comments else ""

问问自己：“我是在添加代码，还是在集成到现有代码中？”

简单胜过抽象

YAGNI：你不会需要它。

不要为假设的未来需求而构建。只有当前任务需要时，才增加复杂性。

避免：

• 只有一种实现方式却使用抽象基类
• 没人要求的配置选项
• 对不可能发生的情况进行错误处理
• 为单个函数包装一层类
• 直接调用可行时使用依赖注入
• 为一种具体类型添加泛型类型参数

三行相似的代码胜过过早抽象。等到出现第三个真实用例时再重构，而不是提前重构。

但简单不意味着混乱。始终保持：

• 清晰描述函数用途的名称
• 将相关代码按逻辑归入模块
• 项目内一致的命名约定
• I/O 与逻辑清晰分离
• 使用显式参数，而不是全局状态或副作用

问问自己：“这个抽象是在解决我眼下遇到的问题，还是我想象出来的问题？”

环境

• 包管理器：uv（不是 pip）
• 虚拟环境：source .venv/bin/activate 或 uv run python -c "..."
• 第三方包：使用 python -c "import pkg; print(pkg.__file__)" 查找源代码，然后阅读。

测试规范

绝不要想当然。在提出计划或退出计划模式之前，运行 python -c "..."，验证关于代码行为、包函数或数据结构的假设。

问问自己：“在基于这个假设继续之前，我是否已经用 python -c 验证过？”

Google 风格文档字符串

• 摘要：使用祈使语气（“Calculate”，而不是“Calculates”）
• Args：列出所有参数及其类型和说明。不要写默认值。缩进 4 个空格。
• 类型：联合类型使用 int | str，形状使用大写字母 (N, M)，内置类型使用小写 list/dict/tuple，Any/Path 首字母大写
• 可选参数：name (type, optional): Description
• Returns：始终将类型放在括号中，即 (type)。不要使用元组类型。多个返回值应分别命名。
• 分节：Examples（>>>）、Notes、References（仅纯文本）。节标题不缩进。
• 省略：没有返回值时省略“Returns:”，没有参数时省略“Args:”，除非至关重要，否则省略“Raises:”
• 类：只写 Attributes 节，省略 Methods/Args。不要将单行文档字符串改成多行。
• __init__：只写 Args。不要写 Examples/Notes/Methods/References。
• 测试：文档字符串只能写单行。
• 删除现有参数说明中的默认值。可以酌情加入简短的 Examples。

问问自己：“新开发者仅凭文档字符串能理解这个函数吗？”

参考文件

编写代码前先阅读对应文件，而不是事后再读：

• references/idiomatic-patterns.md —— 编写循环、推导式、解包、上下文管理器或数据类时阅读。包含 18 个惯用写法及修改前后的代码
• references/zen-of-python.md —— 在两种设计之间做选择，或判断某个抽象是否值得保留时阅读。附注释的 PEP 20
• references/google-style-guide.md —— 决定异常、可变默认值、导入风格、命名或注释时阅读
• references/effective-python-tips.md —— 审查或重构现有代码时阅读。摘自《Effective Python》（Brett Slatkin）的要点