120 lines
3.8 KiB
Markdown
120 lines
3.8 KiB
Markdown
### Coding Standards
|
|
|
|
**Style & Structure**
|
|
- Prefer longer, explicit code over compact one-liners
|
|
- Always include docstrings for functions/classes + inline comments
|
|
- Strongly prefer OOP-style code (classes over functional/nested functions)
|
|
- Strong typing throughout (dataclasses, TypedDict, Enums, type hints)
|
|
- Value future-proofing and expanded usage insights
|
|
|
|
**Data Design**
|
|
- Use dataclasses for internal data modeling
|
|
- Typed JSON structures
|
|
- Functions return fully typed objects (no loose dicts)
|
|
- Snapshot files in JSON or YAML
|
|
- Human-readable fields (e.g., `scan_duration`)
|
|
|
|
**Templates & UI**
|
|
- Don't mix large HTML/CSS blocks in Python code
|
|
- Prefer Jinja templates for HTML rendering
|
|
- Clean CSS, minimal inline clutter, readable template logic
|
|
|
|
**Writing & Documentation**
|
|
- Markdown documentation
|
|
- Clear section headers
|
|
- Roadmap/Phase/Feature-Session style documents
|
|
- Boilerplate templates first, then refinements
|
|
|
|
**Logging**
|
|
- Use structlog (pip package)
|
|
- Setup logging at app start: `logger = logging.get_logger(__file__)`
|
|
|
|
**Preferred Pip Packages**
|
|
- API/Web Server: Flask
|
|
- HTTP: Requests
|
|
- Logging: Structlog
|
|
- Scheduling: APScheduler
|
|
|
|
### Error Handling
|
|
- Custom exception classes for domain-specific errors
|
|
- Consistent error response formats (JSON structure)
|
|
- Logging severity levels (ERROR vs WARNING)
|
|
|
|
### Configuration
|
|
- Each component has environment-specific configs in its own `/config/*.yaml`
|
|
- API: `/api/config/development.yaml`, `/api/config/production.yaml`
|
|
- Web: `/public_web/config/development.yaml`, `/public_web/config/production.yaml`
|
|
- `.env` for secrets (never committed)
|
|
- Maintain `.env.example` in each component for documentation
|
|
- Typed config loaders using dataclasses
|
|
- Validation on startup
|
|
|
|
### Containerization & Deployment
|
|
- Explicit Dockerfiles
|
|
- Production-friendly hardening (distroless/slim when meaningful)
|
|
- Clear build/push scripts that:
|
|
- Use git branch as tag
|
|
- Ask whether to tag `:latest`
|
|
- Ask whether to push
|
|
- Support private registries
|
|
|
|
### API Design
|
|
- RESTful conventions
|
|
- Versioning strategy (`/api/v1/...`)
|
|
- Standardized response format:
|
|
|
|
```json
|
|
{
|
|
"app": "<APP NAME>",
|
|
"version": "<APP VERSION>",
|
|
"status": <HTTP STATUS CODE>,
|
|
"timestamp": "<UTC ISO8601>",
|
|
"request_id": "<optional request id>",
|
|
"result": <data OR null>,
|
|
"error": {
|
|
"code": "<optional machine code>",
|
|
"message": "<human message>",
|
|
"details": {}
|
|
},
|
|
"meta": {}
|
|
}
|
|
```
|
|
|
|
### Dependency Management
|
|
- Use `requirements.txt` and virtual environments (`python3 -m venv venv`)
|
|
- Use path `venv` for all virtual environments
|
|
- Pin versions to version ranges
|
|
- Activate venv before running code (unless in Docker)
|
|
|
|
### Testing Standards
|
|
- Manual testing preferred for applications
|
|
- **API Backend:** Maintain `api/docs/API_TESTING.md` with endpoint examples, curl/httpie commands, expected responses
|
|
- **Unit tests:** Use pytest for API backend (`api/tests/`)
|
|
- **Web Frontend:** If using a web frontend, Manual testing checklist are created in `public_web/docs`
|
|
|
|
### Git Standards
|
|
|
|
**Branch Strategy:**
|
|
- `master` - Production-ready code only
|
|
- `dev` - Main development branch, integration point
|
|
- `beta` - (Optional) Public pre-release testing
|
|
|
|
**Workflow:**
|
|
- Feature work branches off `dev` (e.g., `feature/add-scheduler`)
|
|
- Merge features back to `dev` for testing
|
|
- Promote `dev` → `beta` for public testing (when applicable)
|
|
- Promote `beta` (or `dev`) → `master` for production
|
|
|
|
**Commit Messages:**
|
|
- Use conventional commit format: `feat:`, `fix:`, `docs:`, `refactor:`, etc.
|
|
- Keep commits atomic and focused
|
|
- Write clear, descriptive messages
|
|
|
|
**Tagging:**
|
|
- Tag releases on `master` with semantic versioning (e.g., `v1.2.3`)
|
|
- Optionally tag beta releases (e.g., `v1.2.3-beta.1`)
|
|
|
|
---
|
|
|
|
## Workflow Preference
|
|
I follow a pattern: **brainstorm → design → code → revise** |