Commenti Python — Riga singola, Multiriga e Buone Pratiche

I commenti sono righe nel codice sorgente che l'interprete Python ignora completamente. Esistono per i lettori umani — per spiegare le intenzioni, documentare le decisioni e segnalare problemi — senza influire sull'esecuzione del programma. Questo capitolo tratta ogni tipo di commento Python, quando usarne ciascuno e le convenzioni che mantengono leggibili le grandi codebase.

Commenti su riga singola

Un commento su riga singola inizia con il carattere cancelletto (#). Tutto ciò che si trova dopo il # fino alla fine di quella riga viene ignorato dall'interprete.

# Calculate the area of a circle
radius = 5
area = 3.14159 * radius ** 2
print(area)  # outputs 78.53975

Il commento nell'ultima riga — posizionato dopo il codice eseguibile sulla stessa riga — è chiamato commento inline. Usali con parsimonia; riservali per logiche genuinamente non ovvie piuttosto che per ripetere ciò che il codice già dice.

Quando usare i commenti su riga singola

• Spiega il perché di una decisione, non il cosa fa il codice (il codice mostra già il cosa).
• Segna le soluzioni temporanee: # TODO: replace with database lookup.
• Disabilita temporaneamente una singola riga durante il debug.

# FIXME: division by zero if user_count is 0
average = total_score / user_count

Commenti multiriga

Python non ha una sintassi dedicata per i commenti multiriga come il /* ... */ del linguaggio C. Il modo idiomatico per estendersi su più righe è usare commenti su riga singola consecutivi, ciascuno che inizia con #.

# This function converts a temperature in Celsius to Fahrenheit.
# The formula is: F = (C * 9/5) + 32
# Returns a float rounded to two decimal places.
def celsius_to_fahrenheit(c):
    return round((c * 9 / 5) + 32, 2)

print(celsius_to_fahrenheit(100))  # 212.0
print(celsius_to_fahrenheit(0))    # 32.0

La maggior parte degli editor e IDE Python ti consente di selezionare più righe e attivare/disattivare # su tutte contemporaneamente (di solito Ctrl+/ o Cmd+/).

Docstring — commenti di documentazione strutturati

Python ha una convenzione speciale per le stringhe letterali chiamata docstring (abbreviazione di documentation string). Una docstring è una string con tripli apici posizionata immediatamente dopo un'intestazione def, class o module. Sebbene tecnicamente sia un'espressione stringa e non un commento, funge da meccanismo di documentazione standard ed è accessibile a runtime tramite l'attributo __doc__.

def greet(name):
    """Return a personalised greeting message.

    Args:
        name (str): The name of the person to greet.

    Returns:
        str: A greeting string.
    """
    return f"Hello, {name}!"

print(greet("Alice"))        # Hello, Alice!
print(greet.__doc__)         # prints the docstring above

Stringhe con tripli apici come commenti a blocco

Poiché Python scarta le stringhe letterali non assegnate a nulla, una stringa con tripli apici da sola (non in posizione def/class) viene talvolta usata come commento a blocco informale:

"""
This script processes the daily sales report.
It reads from sales.csv, aggregates by region,
and writes a summary to report.txt.
"""

import csv

Questo schema funziona ma ha un costo sottile: a differenza dei commenti #, l'interprete analizza la stringa e può mantenerla nel bytecode compilato. Per la documentazione a livello di modulo, preferisci una docstring di modulo appropriata (la prima istruzione nel file). Per altre spiegazioni multiriga all'interno delle funzioni, usa righe # consecutive.

Commentare il codice durante il debug

Disabilitare temporaneamente il codice con i commenti è una tecnica di debug comune:

def calculate_discount(price, rate):
    # discount = price * rate        # old flat-rate formula
    discount = price * rate if rate < 1 else price * (rate / 100)
    return price - discount

print(calculate_discount(100, 0.2))   # 80.0
print(calculate_discount(100, 20))    # 80.0

Una volta confermata la correzione, rimuovi le righe commentate invece di lasciarle definitivamente nella codebase — il codice commentato obsoleto confonde i futuri lettori.

Direttive speciali nei commenti

Python e i suoi strumenti riconoscono alcune righe di commento che hanno significato leggibile dalla macchina:

La riga shebang

Sui sistemi Unix-like, la prima riga di uno script può specificare l'interprete:

#!/usr/bin/env python3
# This line tells the OS to run the file with python3.

print("Hello from a standalone script!")

Questa riga è un commento per Python (inizia con #), ma il sistema operativo la utilizza quando il file viene eseguito direttamente (./script.py).

Dichiarazione di codifica

Se il file sorgente utilizza una codifica dei caratteri diversa da UTF-8 (il predefinito da Python 3), dichiarala sulla prima o seconda riga:

# -*- coding: utf-8 -*-

Python 3 usa UTF-8 per impostazione predefinita, quindi questo è raramente necessario oggi, ma potresti incontrarlo nel codice legacy.

Direttive per il type-checker

I type checker come mypy rispettano speciali commenti inline:

x = []  # type: ignore
result = some_function()  # type: ignore[return-value]

Questi sopprimono specifici errori di tipo senza modificare il comportamento a runtime. Consulta il capitolo Variabili Python per maggiori informazioni su come Python gestisce i tipi.

Buone pratiche per i commenti

Seguire queste convenzioni renderà i tuoi commenti genuinamente utili:

PEP 8 — la guida di stile ufficiale di Python — raccomanda:

• I commenti inline devono essere separati dall'istruzione da almeno due spazi.
• Ogni commento inline deve iniziare con # (cancelletto, poi uno spazio).
• I commenti a blocco applicati al codice sottostante devono essere indentati allo stesso livello.

def apply_tax(price, tax_rate):
    # Tax rate is expressed as a decimal (e.g., 0.07 for 7 %).
    # Prices must be non-negative; validation happens upstream.
    tax = price * tax_rate
    return price + tax  # total including tax

Errori comuni da evitare

1. Lasciare commenti TODO senza tracciarli

# TODO: handle the case where the file does not exist
data = open("data.txt").read()

I TODO sono utili durante lo sviluppo, ma dovrebbero essere collegati a un issue tracker, non lasciati indefinitamente nel codice di produzione.

2. Commentare grandi blocchi invece di eliminarli

Il controllo di versione (git) conserva la cronologia. Non c'è bisogno di mantenere il codice commentato per i posteri — eliminalo e affidati a git log se mai dovessi averne bisogno di nuovo.

3. Stile inconsistente

Un misto di #comment, # comment e ## comment nello stesso file fa sembrare la codebase abbandonata. Concordate uno stile e applicatelo in modo coerente.

Riepilogo

I commenti sono uno strumento leggero che porta benefici ogni volta che un altro sviluppatore (o il te del futuro) legge il tuo codice. Per approfondire gli argomenti correlati, consulta Sintassi Python e Variabili Python.

Practice