Home Assistant HACS Component Development Standards
Follow these coding standards and best practices when developing the HACS Room Ventilation Advisor integration for Home Assistant.
Instructions
1. Use Up-to-Date Documentation
Use Context7 to fetch current documentation for libraries and frameworks rather than relying on training dataAlways refer to the latest official [Home Assistant Developer Documentation](https://developers.home-assistant.io/)Align with Home Assistant [architecture decisions](https://developers.home-assistant.io/docs/architecture_index/) and avoid anti-patternsEnsure compatibility with Home Assistant's update cycles and deprecation policies2. General Coding Guidelines
Use English for all code, comments, documentation, and commit messages (mandatory)Write code that is easy to read and understandFollow the principle of least surprise; code should behave as expectedUse descriptive names for variables, functions, and classesAvoid magic numbers; use constants insteadFollow the DRY principle (Don't Repeat Yourself)Keep functions small and focused on a single taskUse comments to explain WHY something is done, not HOWUse version control (Git) for all code changes3. Naming Conventions
Use `PascalCase` for component names, interfaces, and type aliasesUse `camelCase` for variables, functions, and methodsPrefix private class members with underscore (`_`)Use `ALL_CAPS` for constants4. Code Structure
Organize code into modules or packages based on functionalityUse a consistent file structure across the projectKeep related files together (components, styles, tests)5. Commit Message Standards
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification (required for automated release):
`feat`: A new feature`fix`: A bug fix`docs`: Documentation only changes`style`: Formatting changes (white-space, etc.)`refactor`: Code change that neither fixes a bug nor adds a feature`perf`: Performance improvement`test`: Adding or correcting tests`chore`: Build process or tooling changesAdd scope in parenthesis when helpful: `feat(parser): add ability to parse arrays`
For breaking changes, add `BREAKING CHANGE:` to the commit message footer.
6. Code Quality Checks
Before committing, fix all issues from:
ESLint (JavaScript/TypeScript linting & formatting)Ruff (Python linting & formatting)Pylance (Python type checking)Use consistent indentation and formatting throughout the codebase.
7. Home Assistant Specific Guidelines
Follow platform-specific best practices for custom components (sensors, switches, services)Write code that can be upstreamed or reused by the Home Assistant communityAvoid anti-patterns that contradict Home Assistant standardsNever rely on outdated community posts; always use official documentation8. Error Handling
Use try/catch blocks for async operationsAlways log errors with contextual informationUse custom error classes for specific error typesNever swallow errors silentlyProvide user-friendly error messagesAddress all warnings; do not ignore them9. Documentation
Use docstrings for all public functions, classes, and methodsUse Markdown for README files and documentationKeep documentation up-to-date with code changesUse comments to explain complex logic or important decisions10. Testing
Refer to the comprehensive testing guide at `tests/TESTING.md`Follow established patterns for config flow and options flow testsWrite both positive and negative test cases for all functionalityEnsure tests are independent and properly use fixtures from `conftest.py`11. Code Reviews
All code changes must go through peer reviewProvide meaningful descriptions in pull requestsReview code for readability, security, and performanceAsk for clarification rather than making assumptions12. Internationalization (i18n)
Keep all translation files in `/translations/` up-to-date, especially `en.json`Add new keys to `en.json` and `de.json` when UI text is added or changedDo not remove keys without verifying their usage across the codebaseUse consistent key naming for translations**CRITICAL**: All UI texts, including option labels and dropdown values, must be sourced from translation files and must NOT be hardcoded in the codebaseExamples
Good Commit Message
```
feat(sensor): add outdoor air quality monitoring
Add support for outdoor PM2.5 and PM10 sensors to improve
ventilation recommendations based on outdoor air quality.
Closes #123
```
Good Function Structure
```python
def calculate_ventilation_score(
indoor_co2: float,
outdoor_temp: float,
indoor_humidity: float
) -> float:
"""Calculate ventilation recommendation score.
Args:
indoor_co2: Indoor CO2 level in ppm
outdoor_temp: Outdoor temperature in Celsius
indoor_humidity: Indoor relative humidity in percent
Returns:
Score between 0-100 indicating ventilation recommendation strength
"""
# Implementation here
```
Constraints
All UI text MUST use translation files (no hardcoded strings)All code quality checks MUST pass before committingEnglish is mandatory for all code and documentationConventional Commits format is required for all commits