Argomenti, parametri e valori di ritorno nelle funzioni Python: progettare API chiare e sicure

Introduzione

Quando si scrive una funzione in Python, non basta “farla funzionare”: bisogna anche farla funzionare bene. Questo significa scegliere con attenzione gli argomenti che la funzione accetta, i parametri che userà al suo interno e il valore di ritorno che fornirà al chiamante. In altre parole, stiamo definendo una piccola interfaccia di programmazione, cioè un contratto tra chi scrive la funzione e chi la utilizza.

Un sotto-argomento molto utile, spesso sottovalutato, è la progettazione di funzioni con parametri opzionali ben pensati e valori di ritorno strutturati. È un tema pratico perché compare in tantissimi casi reali: calcolo di sconti, validazione dati, formattazione di output, trasformazione di record, gestione di configurazioni. Saperlo usare bene rende il codice più leggibile, riutilizzabile e meno fragile.

In questo tutorial vedremo come distinguere argomenti e parametri, come usare valori di default in modo intelligente e come restituire risultati utili con un valore di ritorno chiaro. L’obiettivo è imparare a scrivere funzioni che siano semplici da chiamare e facili da mantenere.

Codice completo

from typing import Dict, Any


def calcola_totale_carrello(
    prezzo_base: float,
    quantita: int = 1,
    sconto_percentuale: float = 0.0,
    imposta_percentuale: float = 22.0
) -

Spiegazione

Nel codice sopra la funzione calcola_totale_carrello mostra bene il rapporto tra argomenti, parametri e valore di ritorno.

1. Argomenti e parametri non sono la stessa cosa

I parametri sono i nomi definiti nella firma della funzione, ad esempio prezzo_base, quantita, sconto_percentuale e imposta_percentuale. Gli argomenti sono invece i valori reali passati quando la funzione viene chiamata, come 49.90, 3, 10 e 22.

Questa distinzione è importante perché aiuta a leggere il codice con precisione. Quando diciamo “la funzione accetta quattro parametri”, parliamo della sua definizione. Quando diciamo “la funzione è stata chiamata con questi argomenti”, parliamo dell’uso concreto.

2. I parametri con valore di default rendono la funzione più comoda

Abbiamo assegnato valori di default a quantita, sconto_percentuale e imposta_percentuale. Questo significa che il chiamante può omettere alcuni argomenti se non vuole personalizzare quei valori.

Per esempio:

• quantita=1 è una scelta ragionevole per un acquisto singolo.
• sconto_percentuale=0.0 evita di applicare sconti se non specificati.
• imposta_percentuale=22.0 rappresenta un’imposta di default, utile in contesti italiani.

I valori di default sono utili, ma vanno scelti con criterio. Un buon default deve essere sicuro, prevedibile e coerente con il dominio del problema.

3. La validazione dei parametri protegge la funzione

La funzione verifica che i valori ricevuti siano sensati:

• il prezzo base non può essere negativo;
• la quantità deve essere maggiore di zero;
• sconto e imposta devono essere compresi tra 0 e 100.

Questo è fondamentale perché una funzione ben progettata non deve fidarsi ciecamente di chi la chiama. In Python è comune ricevere dati da form, API, file o input utente: la validazione interna evita risultati incoerenti o bug difficili da tracciare.

4. Il valore di ritorno è strutturato e utile

La funzione non restituisce solo un numero, ma un dizionario con tutti i dettagli del calcolo. Questa scelta è pratica perché il chiamante può usare subito i dati senza ricalcolare nulla.

Ad esempio, invece di restituire soltanto il totale finale, possiamo accedere a:

• subtotale
• sconto
• imponibile
• imposta
• totale

Restituire un valore strutturato è spesso meglio di restituire un singolo numero, soprattutto quando la funzione esegue più operazioni e il risultato deve essere spiegabile.

5. Separare calcolo e presentazione è una buona idea

La funzione descrivi_risultato_carrello prende il dizionario prodotto dal calcolo e lo trasforma in testo leggibile. Questo separa due responsabilità diverse:

• calcolare il risultato;
• presentarlo all’utente.

È una best practice importante: una funzione dovrebbe fare una cosa sola, o comunque avere un compito ben definito. Così il codice diventa più facile da testare, modificare e riusare.

Best practice

• Usa nomi chiari per i parametri: un buon nome riduce la necessità di commenti e rende la chiamata più leggibile.
• Preferisci valori di default sensati: evita default ambigui o pericolosi, specialmente con tipi mutabili.
• Valida sempre gli input: se una funzione dipende da vincoli precisi, controllali subito.
• Restituisci dati utili, non solo un numero: un dizionario o una tupla nominata può essere più informativa.
• Non mescolare logica e output: calcolo e stampa dovrebbero restare separati.
• Usa type hints quando possibile: migliorano la leggibilità e aiutano strumenti come linters e IDE.
• Documenta il comportamento della funzione: soprattutto quando ci sono parametri opzionali o regole di validazione.

Un errore comune è creare funzioni con troppi parametri senza una struttura chiara. Se una funzione inizia ad accettare molti valori, chiediti se non sia il caso di raggrupparli in una struttura più adatta, oppure di scomporre il problema in più funzioni più piccole.

Riepilogo

In Python, comprendere bene argomenti, parametri e valori di ritorno è essenziale per scrivere funzioni pulite e affidabili. I parametri definiscono ciò che una funzione si aspetta, gli argomenti sono i valori passati al momento della chiamata e il valore di ritorno rappresenta il risultato finale che la funzione consegna al chiamante.

In questo tutorial abbiamo visto un caso pratico: una funzione che calcola il totale di un carrello. L’esempio ha mostrato come usare parametri con default, come validare gli input e come restituire un risultato strutturato invece di un singolo numero. Questo approccio rende le funzioni più facili da riusare, testare e mantenere nel tempo.

Se vuoi migliorare davvero il tuo codice, pensa alle funzioni come a piccoli componenti con un’interfaccia precisa: pochi parametri ben scelti, valori di ritorno chiari e responsabilità ben separate.

Approfondisci con risorse ufficiali

• Python Documentation - Defining Functions: guida ufficiale sulla definizione delle funzioni e sulla sintassi.
• Python Documentation - Built-in Types: utile per approfondire dizionari, tuple e altri tipi usati nei ritorni.
• Python Documentation - Data model: per capire meglio come Python gestisce oggetti e chiamate di funzione.
• PEP 8: la guida di stile ufficiale per scrivere codice Python leggibile e coerente.
• typing module: documentazione ufficiale per annotazioni di tipo e miglioramento della chiarezza delle API.