Commenti

Perché scrivere commenti?

Immagina di aprire un tuo vecchio quaderno di appunti dopo sei mesi. Se hai scritto solo formule e numeri senza spiegazioni, probabilmente non ricordi più cosa significano.

Nel codice succede la stessa cosa. Un commento è una nota che scrivi nel codice per spiegare cosa sta succedendo. Python ignora completamente i commenti quando esegue il programma: sono messaggi solo per gli esseri umani.

Scrivere buoni commenti è una delle abitudini più importanti di un programmatore.

Commenti su una riga

In Python, un commento inizia con il simbolo #. Tutto quello che viene scritto dopo # sulla stessa riga viene ignorato da Python:

# Questo è un commento: Python lo ignora completamente
print("Ciao!")  # Puoi mettere un commento anche dopo il codice

# Puoi usare i commenti per "disattivare" del codice temporaneamente:
# print("Questa riga non viene eseguita")

Commenti su più righe

Se vuoi scrivere un commento lungo, hai due opzioni.

Opzione 1: Metti # all’inizio di ogni riga

# Questo programma calcola l'area di un rettangolo.
# Prende la base e l'altezza come input
# e stampa il risultato.

Opzione 2: Usa le virgolette triple """..."""

"""
Questo è un blocco di testo su più righe.
Python non lo esegue come codice.
Viene spesso usato all'inizio di un file per descriverlo.
"""

Tecnicamente le virgolette triple creano una stringa di testo, non un vero commento. Ma se non la assegni a nessuna variabile, Python la ignora lo stesso. Vengono usate moltissimo in pratica.

Cosa scrivere (e cosa NON scrivere)

Un buon commento spiega il perché di una scelta, non il cosa fa il codice (quello si dovrebbe capire già leggendo il codice).

# Male: il commento dice l'ovvio, non aggiunge nulla
x = 10  # assegna 10 a x

# Bene: spiega perché usiamo quel numero specifico
VELOCITA_MASSIMA = 130  # limite autostradale in Italia, in km/h

# Bene: spiega una formula non ovvia
area = 3.14159 * raggio ** 2  # formula del cerchio: pi * r²

Le docstring: commenti per le funzioni

Le docstring sono commenti speciali che si mettono subito dentro una funzione (o una classe) per spiegare cosa fa. Si scrivono con le virgolette triple:

def calcola_area(base, altezza):
    """Calcola e restituisce l'area di un rettangolo."""
    return base * altezza

def saluta(nome):
    """
    Stampa un messaggio di benvenuto personalizzato.

    Parametri:
    - nome: il nome della persona da salutare
    """
    print("Ciao, " + nome + "!")

Le docstring sono utili anche perché puoi leggerle dal programma stesso con la funzione help():

help(calcola_area)
# Stampa: Calcola e restituisce l'area di un rettangolo.