Review Goals
Evaluate code quality against the following standards established by this repository:
- [python-code-quality] — code style, type annotations, naming conventions, docstrings
- [python-pytest] — test structure, coverage, test maintainability
- [python-simplifier] — complexity, duplicated code, logical redundancy
- [python-best-practices] — data structure selection, performance, concurrency models, common pitfalls
Review Dimensions and Checklist Items
1. Code Style (against python-code-quality)
Type Annotations
- All function parameters and return values have type annotations
- Use
X | Noneinstead ofOptional[X] - Use built-in generics (
list[X]、dict[K, V]) instead oftyping.List、typing.Dict - The top of the file has
from __future__ import annotations(depending on project configuration)
Naming Conventions
- Class names use PascalCase
- Functions and variables use snake_case
- Constants use UPPER_SNAKE_CASE
- Private members start with
_Start - No shadowing of built-in names (
list、type、next, etc.)
Docstrings
- All public functions and classes have Google-style docstrings
- They describe parameters, return values, and possible exceptions raised
- Docstrings are consistent with the actual implementation
Tool Checks
-
ruff check .No errors -
ruff format --check .No formatting issues -
basedpyrightNo type errors
2. Test Quality (against python-pytest)
Coverage and Completeness
- Core logic test coverage ≥ 80%
- Normal paths, exception paths, and boundary values are all tested
- Each test verifies only one behavior
Readability
- Test names clearly describe the scenario under test and the expected result
- Follow the Arrange-Act-Assert (AAA) pattern
- No leftover debugging
printstatements
Maintainability
- Shared fixtures are placed in
conftest.py - Mocks only target external dependencies (databases, HTTP, filesystems)
- No hardcoded paths or environment-specific dependencies
3. Code Simplicity (against python-simplifier)
Complexity
- Functions do not exceed 30 lines
- Nesting levels do not exceed 3 levels
- Functions have no more than 5 parameters (otherwise consider encapsulating with a dataclass)
Duplicated Code
- No obvious duplicated logic (identical code blocks appearing 2 or more times should be extracted)
- Similar functions have been merged through parameterization
Readability
- No magic numbers or magic strings (use constants or enums)
- Long chains of
if-elif(≥4 branches) have been replaced with dictionary mappings ormatch-case - Use early returns (Guard Clauses) instead of deep nesting
4. Best Practices (against python-best-practices)
Data Structures
- Membership tests use
setinstead oflist - Frequency counting uses
Counter - Queue operations use
dequeinstead oflist
Performance
- Use generators instead of lists for large datasets
- Repeated computation results are cached (
lru_cache/cache) - String concatenation uses
joininstead of+=
Common pitfalls
- No mutable default arguments (
def f(x=[]):) - No incorrect references to loop variables in closures
- and
Nonecomparisons useis/is not
Review conclusion format
At the end of the review, provide the conclusion in the following format:
## 代码审查结论
### ✅ 符合标准的方面
- 类型注解完整,使用了 Python 3.10+ 语法
- 测试遵循 AAA 模式,命名清晰
- ...
### ⚠️ 需要改进的方面
1. `process_data()` 函数缺少返回值类型注解
- 位置:`src/processor.py:42`
- 建议:添加 `-> list[Result]`
2. 测试覆盖率不足
- 位置:`tests/test_processor.py`
- 建议:补充异常路径测试(当输入为空列表时)
3. 魔法数字
- 位置:`src/config.py:15`:`if retries > 3:`
- 建议:提取为常量 `MAX_RETRIES = 3`
### 🚫 必须修复的问题(阻断合并)
- `basedpyright` 报告 2 个类型错误(见下方详情)
- `ruff` 报告 1 个 B006 错误(可变默认参数)
### 总体评分
- 代码风格:⭐⭐⭐⭐☆
- 测试质量:⭐⭐⭐☆☆
- 代码简洁性:⭐⭐⭐⭐⭐
- 最佳实践:⭐⭐⭐⭐☆
Quick check commands
Run the following commands before committing or merging to ensure basic quality:
# 格式化 + lint
ruff format .
ruff check . --fix
# 类型检查
basedpyright
# 运行相关测试(只跑本次修改涉及的模块)
pytest tests/test_affected_module.py -v
# 带覆盖率
pytest tests/test_affected_module.py --cov=src/affected_module --cov-report=term-missing