paperlib/dev-docs/coding-guidelines.md

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.