python-expert-best-practices-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python 3.14+ Expert Best Practices

Python 3.14+ 专家级最佳实践

Simple, pragmatic, opinionated. Only what matters for writing production-grade python code.

简洁、务实、有明确立场。仅涵盖编写生产级Python代码的核心要点。

When to Apply

适用场景

Reference these guidelines when:

Writing Python functions, classes, or modules
Reviewing Python code for error handling issues
Refactoring existing Python codebases
Implementing data validation and API boundaries
Optimizing error detection and debugging patterns

在以下场景中参考本指南：

编写Python函数、类或模块
审查Python代码的错误处理问题
重构现有Python代码库
实现数据验证与API边界定义
优化错误检测与调试模式

Rule Categories by Priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Error Handling	CRITICAL	`dict-` , `operators-`
2	Common Bugs	CRITICAL-HIGH	`no-mutable-` , `no-generic-`
3	Code Clarity	HIGH-MEDIUM	`listcomp-` , `no-inline-`
4	Code Style	LOW	`avoid-` , `unnecessary-`

优先级	类别	影响程度	前缀
1	错误处理	严重	`dict-` , `operators-`
2	常见缺陷	严重-高	`no-mutable-` , `no-generic-`
3	代码清晰度	高-中	`listcomp-` , `no-inline-`
4	代码风格	低	`avoid-` , `unnecessary-`

Quick Reference

速查指南

```
dict-required-keys
```
- Use
```
d[key]
```
for required dictionary keys to fail fast with KeyError
```
no-mutable-defaults
```
- No mutable defaults in function/method parameters
```
operators-return-notimplemented
```
- Return NotImplemented for unsupported operand types and design + vs += intentionally
```
no-generic-except
```
- Avoid generic except clauses to prevent hiding unexpected errors
```
listcomp-no-side-effects
```
- List comprehensions must produce a value you use (no side-effect listcomps)
```
no-inline-imports
```
- Place all import statements at the top of the file
```
avoid-explanatory-comments
```
- Avoid unnecessary comments for self-documenting code
```
unnecessary-else-blocks
```
- Avoid unnecessary else blocks after return/break/continue statements

```
dict-required-keys
```
- 对于必填字典键，使用
```
d[key]
```
以便触发KeyError快速失败
```
no-mutable-defaults
```
- 函数/方法参数中禁止使用可变默认值
```
operators-return-notimplemented
```
- 对于不支持的操作数类型，返回NotImplemented，并合理设计+与+=的行为
```
no-generic-except
```
- 避免使用通用except语句，防止隐藏意外错误
```
listcomp-no-side-effects
```
- 列表推导式必须生成可复用的值（禁止带副作用的列表推导）
```
no-inline-imports
```
- 将所有import语句放在文件顶部
```
avoid-explanatory-comments
```
- 避免不必要的注释，编写自文档化代码
```
unnecessary-else-blocks
```
- 在return/break/continue语句后，避免多余的else块

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/dict-required-keys.md
rules/no-mutable-defaults.md
rules/operators-return-notimplemented.md
rules/no-generic-except.md
rules/listcomp-no-side-effects.md
rules/no-inline-imports.md
rules/avoid-explanatory-comments.md
rules/unnecessary-else-blocks.md

Each rule file contains:

Brief explanation of why it matters
When to use and when not to use the pattern
Implementation requirements
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

阅读单个规则文件获取详细说明与代码示例：

rules/dict-required-keys.md
rules/no-mutable-defaults.md
rules/operators-return-notimplemented.md
rules/no-generic-except.md
rules/listcomp-no-side-effects.md
rules/no-inline-imports.md
rules/avoid-explanatory-comments.md
rules/unnecessary-else-blocks.md

每个规则文件包含：

规则重要性的简要说明
规则的适用与不适用场景
实现要求
错误代码示例及问题说明
正确代码示例及解释
额外背景信息与参考资料