Hardcode nello sviluppo: cos'è, rischi e come evitarlo

Cosa significa “inchiodare” e “hardcodare”

Hardcodare (inchiodare) — incorporare un valore specifico nel codice del programma in modo tale che per modificarlo sia necessario editare il codice sorgente e ricompilare l'applicazione. La metafora “inchiodare” riflette esattamente l'essenza: il valore è fissato permanentemente e può essere staccato dal codice solo con sforzo.

Esempio di hardcode — un URL del server scritto come stringa direttamente nel corpo di una funzione. Se il server si sposta su un altro indirizzo, lo sviluppatore deve trovare la stringa nel codice, modificarla, ricostruire l'applicazione e distribuire una nuova release. In un'applicazione con architettura corretta, tale URL sarebbe stato estratto in un file di configurazione, una variabile d'ambiente o un servizio di configurazione.

Il termine “inchiodare” è più carico emotivamente: sottolinea che il valore è inserito permanentemente, senza possibilità di sostituzione rapida. Nell'ambiente russofono, entrambe le espressioni sono usate come sinonimi completi con connotazione negativa. A volte l'hardcode viene ironicamente chiamato “costante estratta in una costante separata da una costante”.

Perché l'hardcode è considerato un antipattern

Hardcode — un antipattern perché viola i principi di manutenibilità, testabilità ed estendibilità del codice. In codice dove i valori sono “inchiodati”, qualsiasi modifica di ambiente, design o logica richiede ricerca e sostituzione manuali nei sorgenti. Questo aumenta il rischio di errori e rallenta lo sviluppo.

Consideriamo le conseguenze specifiche dell'hardcode usando come esempio una tipica applicazione mobile. Se il margine di tutti i pulsanti è definito da un numero nel codice, non attraverso una risorsa — un cambio di design richiederà di trovare tutte le occorrenze e sostituirle. Se l'URL dell'endpoint è fissato rigidamente — il passaggio tra ambienti (dev, stage, prod) è impossibile senza una ricostruzione.

Esempio di hardcode errato

Una funzione che utilizza numeri magici e stringhe fissate — l'esempio classico di hardcode. Dopo un mese, l'autore non ricorderà cosa significano 18, 0.07 e 2.5. Dopo un anno — nessuno nel team oserà modificare questi numeri, temendo di rompere la logica. Estrarre i valori in costanti nominate rende il codice autodocumentante.

// Cattivo: numeri magici e stringhe
fun calculatePrice(base: Double): Double {
    val tax = base * 0.07
    val tip = base * 0.15
    val discount = if (base > 100) 10 else 0
    return base + tax + tip - discount
}

Impatto sui test

Un URL di database hardcodato non permetterà di eseguire test su un database locale in-memory. Lo sviluppatore dovrà avviare un server completo o modificare il codice prima dei test. Estrarre la configurazione dal codice risolve il problema: i test usano parametri di test, la produzione usa parametri reali, e il codice rimane invariato.

Quando l'hardcode è giustificato: eccezioni alle regole

L'hardcode è un antipattern, ma esistono eccezioni legittime in cui un valore fissato non solo è accettabile, ma anche preferibile. Il confine segue l'asse di mutabilità: se il valore non cambia mai o quasi mai nel ciclo di vita dell'applicazione, può essere hardcodato. Se può potenzialmente cambiare — estraetelo nella configurazione.

Costanti matematiche e fisiche — Pi greco, accelerazione di gravità, numero di millisecondi in un secondo — sono sicure per l'hardcode. Sono definite dalla natura o dagli standard e non cambieranno. Dimensioni di array costanti definite da specifica possono anch'esse essere fissate, ma con un commento sull'origine del numero.

Esempio di hardcode giustificato

Il numero di millisecondi in un secondo è una costante stabile definita dallo standard temporale. Non ha senso estrarla in un config, perché non cambierà mai. Tuttavia, anche queste costanti è meglio dichiararle con un nome chiaro, in modo che il codice non contenga “numeri magici”: invece di 1000, scrivete MILLISECONDS_IN_SECOND.

// Hardcode giustificato: costanti stabili
private const val MILLIS_IN_SECOND = 1000
private const val LOGIN_TIMEOUT_SECONDS = 30

fun formatDuration(ms: Long): String {
    val seconds = ms / MILLIS_IN_SECOND
    return "${seconds} sec."
}

Alternative all'hardcode: configurazioni, ENV, DI

Esistono diversi modi comprovati per evitare l'hardcode, ciascuno adatto al proprio tipo di valore. La scelta dell'alternativa dipende dalla frequenza con cui il valore cambia e da chi lo modifica: sviluppatore, devops o utente finale.

File di configurazione

Per URL di server, chiavi API e feature flag, utilizzate file di configurazione in formato JSON, YAML o TOML. Su Android, è build.gradle con buildConfigField o res/values/config.xml. Su iOS — Info.plist o xcconfig. Le configurazioni vengono compilate insieme all'applicazione, ma possono essere diverse per diversi schemi di build.

Variabili d'ambiente

Per segreti (token, password) e parametri d'ambiente, utilizzate variabili d'ambiente. Non finiscono nel repository e possono differire sui server dev, stage e prod. Nello sviluppo mobile, le variabili d'ambiente sono spesso emulate attraverso schemi di build di Xcode o build flavors in Gradle.

Risorse dell'applicazione

Stringhe, colori, dimensioni, immagini dovrebbero essere estratti in file di risorse: strings.xml su Android, Localizable.strings su iOS, file ARB in Flutter. Questo facilita la localizzazione, l'adattamento a schermi diversi e il tema scuro. Modificare una stringa nelle risorse non richiede riscrittura del codice.

<!-- Android: res/values/strings.xml -->
<resources>
    <string name="app_name">MyApp</string>
    <string name="api_base_url">https://api.example.com</string>
</resources>

Iniezione di dipendenze (DI)

Per servizi e provider, utilizzate Dependency Injection tramite Dagger, Hilt o Koin su Android, Swinject su iOS. I framework DI permettono di sostituire le implementazioni al volo — per test, per ambienti diversi, per utenti diversi. Questo è il più alto livello di astrazione, dove “l'inchiodatura” del valore viene sostituita dall'iniezione esterna.

Come rifattorizzare codice hardcodato

Il refactoring dell'hardcode è il processo di estrazione dei valori fissati nella configurazione o nelle risorse. È una delle operazioni di refactoring più sicure, se eseguita metodicamente. La sequenza descritta di seguito è adatta a qualsiasi linguaggio e piattaforma.

Passo 1: trova tutti i numeri magici e le stringhe

La ricerca può essere effettuata tramite IDE (Search in Project) o script. Cerca stringhe, URL, letterali numerici, dimensioni, timeout. Attenzione particolare — ai valori ripetuti: se lo stesso numero appare in cinque punti, è un candidato per diventare una costante. Usa grep o la ricerca integrata di IDEA / Xcode.

Passo 2: sostituisci con costanti nominate

Per ogni valore trovato, crea una costante con un nome significativo. Raggruppa le costanti per moduli o classi. Il nome deve spiegare cosa significa il valore, non come viene usato: API_TIMEOUT, non TIMEOUT_30. Dopo la sostituzione, nessun numero nel codice deve rimanere senza spiegazione.

// Prima: numero magico 0.4
let cardHeight = screenHeight * 0.4

// Dopo: costante nominata
private let cardHeightRatio: CGFloat = 0.4
let cardHeight = screenHeight * cardHeightRatio

Passo 3: estrai nella configurazione o nelle risorse

Se il valore può variare tra build o ambienti — estraetelo in un file di configurazione o nelle risorse dell'applicazione. Per le stringhe, utilizzate file di localizzazione. Per gli URL — build config o xcconfig. Per le dimensioni — file di risorse (dimens.xml su Android). Verificate che l'applicazione si compili e funzioni correttamente dopo l'estrazione.

Passo 4: scrivi un test

Dopo il refactoring, scrivi un test che verifichi che la configurazione venga caricata correttamente e che i valori corrispondano a quelli attesi. Se in futuro qualcuno modificherà il config, il test segnalerà la discrepanza. Un test sulla configurazione è un modo rapido e affidabile per prevenire regressioni.

Passo 5: rimuovi i duplicati

Dopo l'estrazione nel config, verifica che tutti i punti che utilizzavano il vecchio valore facciano riferimento all'unica fonte. Rimuovi il codice commentato e le vecchie costanti che non sono più utilizzate. Finalizza il refactoring con un commit il cui messaggio descriva quali valori sono stati estratti e dove.