35 lines
1.6 KiB
Plaintext
35 lines
1.6 KiB
Plaintext
---
|
|
description: Python style for CelerisLab — path header, docstrings, English comments
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Python style (CelerisLab)
|
|
|
|
## File header
|
|
|
|
- Every `src/CelerisLab/**/*.py` file starts with a single-line path comment so agents can orient without reading the body:
|
|
- Format: `# CelerisLab/<path_under_package>` (e.g. `# CelerisLab/simulation.py`).
|
|
- Match the real path under `CelerisLab/` after edits or moves.
|
|
|
|
## Language
|
|
|
|
- All comments and docstrings in Python source are **English**. User-facing prose in `configs/CONFIG.md` may stay Chinese if that file is explicitly maintained for Chinese readers.
|
|
|
|
## Docstrings and structure
|
|
|
|
- Module docstring: one-line summary plus at least one structured block where useful (`Usage::`, `Responsibilities:`, `Design:`).
|
|
- Public classes and public functions/methods should have a docstring that states purpose; use Google-style sections (`Args:`, `Returns:`, `Raises:`) when parameters or return value are non-obvious.
|
|
- Section dividers in long files: `# -- Section name ---------------------------------------` (consistent with existing files like `simulation.py`).
|
|
|
|
## Types
|
|
|
|
- Prefer type hints on public APIs (`Simulation`, `ObjectManager`, `LBMField`, config loaders). Completeness can improve incrementally; do not block features on perfect annotation coverage.
|
|
|
|
## Imports
|
|
|
|
- Avoid obvious dead imports when touching a file, but **do not** run broad “import cleanup only” refactors as a standalone task unless asked.
|
|
|
|
## Placeholders
|
|
|
|
- Stub methods: `pass` plus a short docstring; mark intent with `(placeholder)` or `(future)` where appropriate.
|