6.3 KiB
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.
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
def build(name: str) -> Identifier:
Non consentito
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.
@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
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.
-
Il codice deve essere leggibile prima di essere intelligente.
-
L'esplicito è preferibile all'implicito.
-
Ogni classe possiede una sola responsabilità.
-
Il dominio non conosce l'infrastruttura.
-
Nessuna dipendenza circolare.
-
Nessun TODO nel codice.
-
Nessun codice morto.
-
Nessun wildcard import.
-
Nessuna eccezione generica.
-
Ogni nuova funzionalità deve essere testabile.
-
Ogni modifica deve rispettare la Software Architecture Specification.
-
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.