Perché lo scopo di una funzione dovrebbe essere evidente per un codice più pulito

Regola
Rendi lo scopo di una funzione evidente.
I nomi delle funzioni devono comunicare chiaramente cosa
fa la funzione senza richiedere ai lettori di esaminare l'implementazione.

Linguaggi supportati: 45+

Introduzione

I nomi delle funzioni che non rivelano il loro scopo costringono gli sviluppatori a leggere l'intera implementazione per comprenderne il comportamento. Una funzione chiamata process() oppure handle() potrebbe fare qualsiasi cosa, richiedendo uno sforzo mentale per dedurre il suo reale proposito. Nomi chiari e descrittivi come validateUserEmail() oppure calculateOrderTotal() comunicano immediatamente l'intento, rendendo il codice autoesplicativo.

Perché è importante

Manutenibilità del codice: Nomi di funzione poco chiari rallentano la comprensione. Gli sviluppatori perdono tempo a leggere le implementazioni per capire cosa fanno le funzioni invece di concentrarsi sulla logica di business. Questo problema si amplifica quando si ritorna sul codice a distanza di mesi o quando si uniscono nuovi membri al team.

Utilizzo errato: Nomi di funzione ambigui aumentano la probabilità di un utilizzo improprio. Una funzione chiamata update() potrebbe convalidare, trasformare, persistere o inviare notifiche, portando gli sviluppatori a usarla in modo errato poiché il nome non ne specifica il comportamento. I nomi chiari prevengono un uso scorretto documentando vincoli ed effetti collaterali.

Esempi di codice

❌ Non conforme:

function process(data) {
    const result = data.map(item => ({
        ...item,
        processed: true,
        timestamp: Date.now()
    }));
    db.save(result);
    notifyService.send(result);
    return result;
}

Perché è errato: Il nome process() non rivela nulla su ciò che accade ai dati. I lettori devono esaminare l'implementazione per scoprire che trasforma gli elementi, li salva nel database e invia notifiche. Gli effetti collaterali e le responsabilità della funzione rimangono nascosti.

✅ Conforme:

function markItemsAsProcessedAndSave(data) {
    const processedItems = data.map(item => ({
        ...item,
        processed: true,
        timestamp: Date.now()
    }));
    db.save(processedItems);
    notifyService.send(processedItems);
    return processedItems;
}

Perché questo è importante: Il nome indica esplicitamente che la funzione contrassegna gli elementi come elaborati e li salva. I lettori comprendono immediatamente lo scopo principale della funzione senza dover leggere l'implementazione. Il nome lascia intuire gli effetti collaterali (il salvataggio nel database), impostando le giuste aspettative.

Conclusione

I nomi delle funzioni dovrebbero rispondere alla domanda "cosa fa?" senza richiedere l'ispezione del codice. Includi verbi che descrivono le azioni e sostantivi che descrivono i target. Se un nome diventa troppo lungo, probabilmente la funzione fa troppe cose e dovrebbe essere suddivisa.