51 lines
1.2 KiB
Markdown
51 lines
1.2 KiB
Markdown
# Coding Guidelines
|
|
|
|
## General style
|
|
|
|
- Prefer straightforward Python
|
|
- Use type hints
|
|
- Keep functions small and focused
|
|
- Add docstrings to public functions and classes
|
|
- Avoid overengineering
|
|
- Prefer composition over deep inheritance
|
|
|
|
## Error handling
|
|
|
|
- Fail clearly
|
|
- Provide helpful error messages
|
|
- Distinguish user-facing CLI errors from internal exceptions
|
|
- Avoid silently swallowing errors
|
|
|
|
## Logging
|
|
|
|
- Use structured and informative logging where useful
|
|
- Avoid noisy logs in normal CLI output
|
|
- Keep machine-readable command output clean when `--json` is used
|
|
|
|
## File operations
|
|
|
|
- Be careful with moves, copies, and overwrites
|
|
- Prefer atomic writes for JSON files when possible
|
|
- Never corrupt existing metadata due to partial writes
|
|
|
|
## Idempotence
|
|
|
|
Where possible, commands should behave safely when run multiple times.
|
|
|
|
Examples:
|
|
- re-importing the same file should detect duplicates
|
|
- `render-summary` should be repeatable
|
|
- `reindex` should be safe to rerun
|
|
|
|
## Testing
|
|
|
|
Add tests for:
|
|
- path layout logic
|
|
- metadata read/write behavior
|
|
- duplicate detection
|
|
- reindex behavior
|
|
- summary rendering
|
|
- search behavior
|
|
- CLI output contracts for core commands
|
|
|
|
Prefer unit tests for core logic and targeted integration tests for CLI behavior. |