code-quality

Python 代码质量

在评审或自我评审期间检查高价值的 Python 代码质量反模式。 此技能侧重评审：涵盖评审者（或 linter）应指出的正确性和可读性缺陷， 与测试机制（pytest）和整个代码库健康度评分（code-quality-scoring）相区分。

**来源说明：**这些反模式源自 CAST Highlight 的 Python 代码质量指标 （https://doc.casthighlight.com/），其主要参考来源是 PEP 8 和 Python 数据模型。若某条规则与 PEP 8 一致，则以 PEP 8 为准。所有示例均为原创。

何时使用此技能

当任务是**“这段 Python 代码是否整洁且正确？”**时使用，例如：

• 评审拉取请求，并检查是否存在以下缺陷。
• 提交 PR 前进行自我评审。
• 配置 ruff/pylint/mypy 规则，让 CI 自动捕获这些问题。
• 编写或更新团队的 Python 代码质量指南。

不要将此技能用于测试机制（请使用 pytest 技能），也不要用于评估整个代码库 的健康状况和技术债务（请使用 code-quality-scoring 技能）。

核心反模式（摘要）

六种最值得关注的 Python 反模式。参考文档中每种反模式都包含不合规/合规示例 以及“如何测试”的说明：

• 自定义异常必须继承自 Exception — 预期会被抛出的类若继承自 object， 会在运行时失败，并导致所有 except 子句出错。
• 比较单例时使用 is，而非 == — 对 None/True/False 使用 is/is not （PEP 8）；is 仅用于单例，绝不可用于值比较。
• 避免裸 except 或范围过宽的 except — 捕获你能处理的最具体类型； 通用的 except Exception 只能作为最后位置的兜底处理，并记录日志或重新抛出异常。
• 避免通配符导入（from x import *）— 这会隐藏依赖、可能造成无提示的名称冲突， 并妨碍静态分析。
• 用具名常量替代魔法数字 — 将不明显的字面值提升为有文档说明的具名常量。
• 移除未使用的局部变量 — 无用赋值会误导读者，还可能掩盖原本应使用某个值的 bug。

最佳实践

• 在 CI 中设置门禁。 大多数问题都能通过 ruff（F403/F405 通配符导入、 F841 未使用的局部变量、E711/E712 单例比较）、pylint 和 mypy 以较低成本 检查。将 lint 步骤放入 CI，让评审精力集中在判断上，而非机械检查。
• 优先使用具体的异常处理器。 按从具体到宽泛的顺序排列处理器；将通用的 except Exception 留作记录日志并重新抛出异常的最后手段。
• 命名要体现意图，而非数值。 常量的名称能说明为何存在某个阈值；单独的字面值则毫无说明。

反模式（应避免的做法）

• 自定义异常继承自 object 或直接继承自 BaseException。
• 使用 == None、== True 或 is "some literal"。
• 使用会吞掉控制流信号的裸 except: 或 except BaseException:。
• 在经过整理且显式定义了 __all__ 的 __init__.py 之外使用 from module import *。
• 在业务逻辑中使用没有解释的数值字面值。
• 重构后遗留已赋值但从未读取的局部变量。

导航

• quality-antipatterns.md：六种反模式各自的 不合规与合规示例，以及“如何测试”的说明。

相关技能

• pytest（toolchains/python/testing/pytest）：测试机制 — fixtures、 参数化、模拟。此处的若干反模式（范围过宽的 except、格式错误的异常类）会直接导致测试不稳定。
• code-review-standards（universal/process/code-review-standards）：项目级、 标注严重程度的评审清单，其中包含这些反模式的对应项。
• code-quality-scoring（universal/quality/code-quality-scoring）：评估整个代码库的 健康状况和技术债务，而非单项问题。