Perché dovresti rendere evidente lo scopo di una funzione per ottenere un codice più chiaro

Regola
Regola una funzione scopo sia evidente.
Nome delle funzioni dovrebbero comunicare chiaramente comunicare cosa il funzione
fa senza richiedere ai lettori di esaminare l' implementazione.

Lingue supportate: 45+

Introduzione

I nomi delle funzioni che non ne rivelano lo scopo costringono gli sviluppatori a leggere l'intera implementazione per comprenderne il comportamento. Una funzione denominata process() oppure handle() potrebbe significare qualsiasi cosa, richiedendo uno sforzo mentale per dedurne il vero scopo. Nomi chiari e descrittivi come validateUserEmail() oppure calculateOrderTotal() comunicare immediatamente l'intento, rendendo il codice autodocumentante.

Perché è importante

Manutenibilità del codice: i nomi delle funzioni 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 aggrava quando si riprende a lavorare sul codice dopo mesi o quando entrano a far parte del team nuovi membri.

Uso errato: I nomi ambigui delle funzioni aumentano il rischio di un uso improprio. Una funzione denominata aggiorna() potrebbe servire a convalidare, trasformare, memorizzare o inviare notifiche, portando gli sviluppatori a utilizzarlo in modo errato poiché il nome non ne specifica il comportamento. I nomi chiari prevengono gli usi impropri documentando i vincoli e gli 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é è sbagliato: Il nome process() non rivela nulla su ciò che accade ai dati. I lettori devono esaminare l'implementazione per capire che essa trasforma gli elementi, li salva nel database e invia notifiche. Gli effetti collaterali e le responsabilità della funzione sono 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é è 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 doverne leggere l'implementazione. Il nome suggerisce la presenza di effetti collaterali (salvataggio nel database), creando aspettative adeguate.

Conclusione

I nomi delle funzioni dovrebbero rispondere alla domanda "A cosa serve questa funzione?" senza che sia necessario esaminare il codice. Includete verbi che descrivono azioni e sostantivi che descrivono gli obiettivi. Se un nome diventa troppo lungo, probabilmente la funzione svolge troppe operazioni e dovrebbe essere suddivisa.