# SMAVS Coding Standards **Version:** 1.0.0 **Status:** Approved **Project:** Spiral – SMAVS Composition Engine --- # 1. Scopo Questo documento definisce gli standard ufficiali di sviluppo del framework **SMAVS (Su Misura Al Vostro Sistema)**. Ogni file del progetto deve rispettare le regole qui descritte. L'obiettivo è garantire: - uniformità del codice; - elevata leggibilità; - semplicità di manutenzione; - coerenza architetturale; - qualità costante durante l'intero ciclo di vita del framework. Le presenti regole costituiscono lo standard ufficiale di sviluppo del progetto. --- # 2. Principi Fondamentali Il codice deve sempre rispettare i seguenti principi. ## Leggibilità Il codice viene letto molte più volte di quante venga scritto. La leggibilità ha sempre priorità rispetto alla brevità. --- ## Esplicitezza L'esplicito è sempre preferibile all'implicito. Il comportamento del codice deve risultare evidente senza richiedere interpretazioni. --- ## Determinismo Ogni componente deve produrre sempre lo stesso risultato a parità di input. --- ## Immutabilità I modelli del dominio sono immutabili. --- ## Single Responsibility Ogni classe possiede una singola responsabilità. --- ## Composition over Inheritance La composizione è sempre preferibile all'ereditarietà. --- ## Dependency Inversion Le dipendenze devono sempre puntare verso le astrazioni. --- ## Testabilità Ogni componente deve poter essere testato in isolamento. --- # 3. Convenzioni Generali ## Versione Python Python 3.11+ --- ## Formatter Ruff Format --- ## Linter Ruff --- ## Type Checker MyPy --- ## Testing Pytest --- ## Coverage Coverage minimo: 95% --- # 4. Convenzioni di Naming ## Package snake_case ``` shared value_objects analysis composition ``` --- ## Moduli snake_case ``` identifier.py module_registry.py composition_context.py ``` --- ## Classi PascalCase ``` Identifier CompositionContext ModuleRegistry ``` --- ## Funzioni snake_case ``` build_context() resolve_modules() ``` --- ## Variabili snake_case ``` execution_plan module_registry ``` --- ## Costanti UPPER_CASE ``` DEFAULT_PRIORITY MAX_DEPTH ``` --- ## Membri privati Singolo underscore ``` _identifier _registry ``` --- # 5. Organizzazione della Repository Ogni package deve contenere esclusivamente componenti appartenenti alla propria responsabilità. Non sono consentite dipendenze circolari. --- # 6. Organizzazione dei File Ogni file Python deve seguire rigorosamente il seguente ordine. ``` Module Docstring ↓ Future Imports ↓ Standard Library ↓ Third Party Imports ↓ Project Imports ↓ __all__ ↓ Constants ↓ Classi ↓ Funzioni ``` --- # 7. Organizzazione degli Import Gli import devono essere ordinati nel seguente modo. ```python from __future__ import annotations from dataclasses import dataclass from pathlib import Path from typing import Final from smavs.shared... ``` Non sono consentiti import inutilizzati. Non sono consentiti wildcard import. ``` from package import * ``` --- # 8. Docstring Ogni modulo pubblico deve possedere una docstring. Ogni classe pubblica deve possedere una docstring. Ogni metodo pubblico deve possedere una docstring quando il comportamento non è immediatamente evidente. Lo stile adottato è **Google Style**. --- # 9. Type Hinting Tutte le funzioni devono utilizzare typing completo. Consentito ```python def build(name: str) -> Identifier: ``` Non consentito ```python def build(name): ``` --- Mai utilizzare ``` list dict tuple set ``` Utilizzare sempre ``` list[str] dict[str, str] tuple[int, ...] set[str] ``` --- # 10. Dataclass Tutti i Value Object devono essere dichiarati nel seguente modo. ```python @dataclass( frozen=True, slots=True, ) ``` Le dataclass mutabili non sono consentite nel dominio. --- # 11. Protocol Le interfacce del Core devono essere implementate tramite Protocol. Non utilizzare classi astratte salvo casi eccezionali. --- # 12. Value Object I Value Object devono: - essere immutabili; - essere hashable; - essere confrontabili; - non possedere identità. --- # 13. Entity Le Entity devono: - possedere un Identifier; - mantenere la propria identità; - incapsulare il proprio stato. --- # 14. Aggregate Root Ogni Aggregate Root è responsabile della consistenza del proprio Aggregate. Le modifiche interne devono essere sempre controllate dall'Aggregate Root. --- # 15. Domain Events I Domain Event rappresentano fatti già accaduti. Sono immutabili. --- # 16. Exceptions È vietato utilizzare ```python raise Exception(...) ``` Ogni errore deve derivare da: ``` SMAVSError ``` --- # 17. Logging Utilizzare esclusivamente logging strutturato. Non utilizzare print(). --- # 18. Testing Ogni componente deve possedere test unitari. La struttura deve seguire il pattern: ``` Arrange Act Assert ``` --- Ogni test deve verificare un solo comportamento. --- # 19. Commenti I commenti devono spiegare il perché. Mai spiegare il cosa. --- # 20. Refactoring Prima di effettuare un refactoring verificare: - retrocompatibilità; - copertura dei test; - conformità alla SAS. --- # 21. Checklist prima del Commit Verificare sempre: - Ruff - MyPy - Pytest - Coverage - Pre-Commit Tutti i controlli devono risultare verdi. --- # 22. Checklist prima della Pull Request La Pull Request deve: - compilare correttamente; - superare la CI; - mantenere il coverage; - rispettare la SAS; - rispettare la Roadmap. --- # 23. Regole Fondamentali Le seguenti regole sono considerate invarianti del progetto. 1. Il codice deve essere leggibile prima di essere intelligente. 2. L'esplicito è preferibile all'implicito. 3. Ogni classe possiede una sola responsabilità. 4. Il dominio non conosce l'infrastruttura. 5. Nessuna dipendenza circolare. 6. Nessun TODO nel codice. 7. Nessun codice morto. 8. Nessun wildcard import. 9. Nessuna eccezione generica. 10. Ogni nuova funzionalità deve essere testabile. 11. Ogni modifica deve rispettare la Software Architecture Specification. 12. Ogni implementazione deve seguire rigorosamente l'Implementation Roadmap. --- # 24. Stato della Specifica Questo documento costituisce lo standard ufficiale di sviluppo del framework SMAVS. Ogni nuovo contributo al progetto deve rispettare integralmente le regole qui definite.