515 lines
6.3 KiB
Markdown
515 lines
6.3 KiB
Markdown
# 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.
|