156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
# EU-Utility Quality Standards
|
|
|
|
This document defines the quality standards for EU-Utility to maintain peak code quality.
|
|
|
|
## Code Organization
|
|
|
|
```
|
|
EU-Utility/
|
|
├── core/ # Core functionality
|
|
│ ├── __init__.py
|
|
│ ├── main.py # Application entry point
|
|
│ ├── api/ # API layer
|
|
│ │ ├── __init__.py
|
|
│ │ ├── nexus_api.py
|
|
│ │ └── external_api.py
|
|
│ ├── services/ # Business logic
|
|
│ │ ├── __init__.py
|
|
│ │ ├── ocr_service.py
|
|
│ │ ├── screenshot.py
|
|
│ │ └── data_store.py
|
|
│ ├── ui/ # UI components
|
|
│ │ ├── __init__.py
|
|
│ │ ├── overlay.py
|
|
│ │ ├── dashboard.py
|
|
│ │ └── widgets/
|
|
│ └── utils/ # Utilities
|
|
│ ├── __init__.py
|
|
│ ├── security.py
|
|
│ └── helpers.py
|
|
├── plugins/ # Plugin system
|
|
│ ├── __init__.py
|
|
│ ├── base_plugin.py
|
|
│ ├── plugin_manager.py
|
|
│ └── builtin/ # Built-in plugins
|
|
├── tests/ # Test suite
|
|
│ ├── __init__.py
|
|
│ ├── test_core/
|
|
│ ├── test_plugins/
|
|
│ └── test_integration/
|
|
├── docs/ # Documentation
|
|
├── assets/ # Static assets
|
|
├── config/ # Configuration files
|
|
├── scripts/ # Utility scripts
|
|
├── setup.py # Package setup
|
|
├── pyproject.toml # Modern Python config
|
|
├── requirements.txt # Dependencies
|
|
├── requirements-dev.txt # Dev dependencies
|
|
├── Makefile # Build automation
|
|
├── LICENSE # MIT License
|
|
├── CHANGELOG.md # Version history
|
|
├── CONTRIBUTING.md # Contribution guide
|
|
└── README.md # Project readme
|
|
```
|
|
|
|
## Naming Conventions
|
|
|
|
- **Files**: `snake_case.py`
|
|
- **Classes**: `PascalCase`
|
|
- **Functions/Methods**: `snake_case()`
|
|
- **Constants**: `UPPER_SNAKE_CASE`
|
|
- **Private**: `_leading_underscore`
|
|
- **Protected**: `_single_leading_underscore`
|
|
|
|
## Code Style
|
|
|
|
- Follow PEP 8
|
|
- Maximum line length: 100 characters
|
|
- Use type hints for all function signatures
|
|
- Docstrings for all public APIs (Google style)
|
|
- Comments for complex logic
|
|
|
|
## Documentation Standards
|
|
|
|
### README.md
|
|
- Clear project description
|
|
- Installation instructions
|
|
- Quick start guide
|
|
- Feature list
|
|
- Screenshots/GIFs
|
|
- Contributing link
|
|
- License
|
|
|
|
### Function Docstrings
|
|
```python
|
|
def example_function(param1: str, param2: int) -> bool:
|
|
"""Short description.
|
|
|
|
Longer description if needed. Can span multiple
|
|
lines and provide detailed context.
|
|
|
|
Args:
|
|
param1: Description of param1.
|
|
param2: Description of param2.
|
|
|
|
Returns:
|
|
Description of return value.
|
|
|
|
Raises:
|
|
ValueError: When param2 is negative.
|
|
|
|
Example:
|
|
>>> example_function("test", 42)
|
|
True
|
|
"""
|
|
pass
|
|
```
|
|
|
|
## Testing Standards
|
|
|
|
- Unit tests for all functions
|
|
- Integration tests for workflows
|
|
- Minimum 80% code coverage
|
|
- Tests must pass before merging
|
|
|
|
## Security Standards
|
|
|
|
- No hardcoded credentials
|
|
- Input validation on all user inputs
|
|
- Use parameterized queries
|
|
- Secure defaults
|
|
- Regular dependency updates
|
|
|
|
## Performance Standards
|
|
|
|
- Profile before optimizing
|
|
- Use async for I/O operations
|
|
- Cache expensive operations
|
|
- Lazy loading for heavy resources
|
|
- Memory cleanup on exit
|
|
|
|
## Git Standards
|
|
|
|
- Commit messages: `type(scope): description`
|
|
- Types: feat, fix, docs, style, refactor, test, chore
|
|
- One logical change per commit
|
|
- Reference issues in commits
|
|
- Squash before merging to main
|
|
|
|
## Release Process
|
|
|
|
1. Update version in `__init__.py`
|
|
2. Update CHANGELOG.md
|
|
3. Run full test suite
|
|
4. Create git tag: `git tag vX.Y.Z`
|
|
5. Push to origin: `git push origin vX.Y.Z`
|
|
6. Create GitHub release
|
|
|
|
## Code Review Checklist
|
|
|
|
- [ ] Code follows style guide
|
|
- [ ] Tests added/updated
|
|
- [ ] Documentation updated
|
|
- [ ] No security vulnerabilities
|
|
- [ ] Performance acceptable
|
|
- [ ] Backwards compatible (or properly versioned)
|