Commenti in Python: su una riga, su più righe e docstring

I commenti sono per le persone

Python ignora i commenti. Tutto qui. Qualsiasi cosa tu segni come commento è invisibile all'interprete: c'è solo per chi legge il codice, che di solito sei tu fra sei mesi, mentre ti chiedi cosa avessi in mente.

Detto questo, un commento che ripete semplicemente ciò che il codice fa in modo evidente non vale la pena di essere scritto. I commenti migliori spiegano il perché: un vincolo, un aggiramento, una decisione che non risulta ovvia dal codice. Il codice ti dice già cosa sta succedendo.

Commenti su una riga con #

La forma di base è un # seguito dalla tua nota:

# Calculate the tax portion of the total.
total = 100
tax = total * 0.08
print(tax)

Puoi anche aggiungere un breve commento alla fine di una riga. Per convenzione, lascia almeno due spazi prima del #:

refresh_interval = 300  # seconds; keep in sync with the dashboard config
print(refresh_interval)

Python legge un # in qualsiasi punto fuori da una stringa e tratta il resto della riga come commento. Quel "fuori da una stringa" è importante: # tra virgolette è solo un carattere.

url = "https://example.com/#section-2"  # the real comment starts here
print(url)

Il #section-2 dentro la stringa fa parte dell'URL. Python passa in modalità "commento" solo con il # che segue la chiusura della stringa.

Commentare più righe

Python non ha un commento a blocco /* */. Per saltare più righe, metti # all'inizio di ciascuna:

# This is a block comment.
# It spans several lines.
# Each line starts with its own #.
print("only this line actually runs")

Quasi mai scriverai quei # a mano. Ogni editor decente ha una scorciatoia per "attivare/disattivare il commento di riga" che aggiunge o toglie # su tutte le righe selezionate:

• VS Code: Cmd + / (macOS) oppure Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / oppure Ctrl + /
• Vim: dipende dai plugin; vim-commentary associa gcc a una singola riga e gc a una selezione.

Impara una volta la scorciatoia del tuo editor, e "commentare questo blocco per provare una cosa" diventa un'operazione da un tasto.

Il trucco della stringa tra triple virgolette (e perché non è un vero commento)

A volte vedrai codice come questo:

"""
This block looks like a comment
but it's actually a string literal
that nothing uses.
"""
print("hi")

Tecnicamente è un'espressione stringa che viene scartata. Python la analizza, la valuta e butta via il risultato. Si comporta come un commento, ma non lo è. Dal punto di vista dello stile, è una buona idea solo in un punto specifico: come docstring.

Docstring: l'unico posto dove stanno bene le triple virgolette

Una docstring è una stringa tra triple virgolette messa come primissima istruzione di una funzione, una classe o un modulo. Python la riconosce come documentazione e la rende disponibile durante l'esecuzione tramite la funzione help() e l'attributo __doc__:

def discount(price, percent):
    """Return the final price after applying a percentage discount.

    price is a number; percent is between 0 and 100.
    """
    return price * (1 - percent / 100)

print(discount(50, 20))
help(discount)

Due cose rendono comode le docstring:

1. Strumenti come gli IDE, help() e i generatori di documentazione le leggono automaticamente. Un commento sopra la funzione non ottiene nulla del genere.
2. Descrivono la funzione nel punto in cui viene chiamata: quando qualcuno passa il mouse su discount(...) nel proprio editor, la docstring compare come suggerimento.

Esiste una convenzione (PEP 257) su cosa mettere in una docstring: un riassunto di una riga sulla prima riga, una riga vuota, poi una descrizione più lunga se serve. Non preoccuparti del formato esatto il primo giorno: una semplice riga è comunque molto meglio di nessuna docstring.

Cosa dicono davvero i buoni commenti

Qualche linea guida che ti risparmierà parecchi grattacapi più avanti:

• Preferisci descrivere il perché anziché il cosa. # Loop over the users è rumore; # Retry on 503 - Redis sometimes dies mid-deploy vale oro.
• Aggiorna i commenti quando cambi il codice. Un commento sbagliato è peggio di nessun commento. I commenti obsoleti ingannano attivamente chi leggerà in futuro.
• Non commentare codice per poi lasciarlo lì. Se non ti serve, cancellalo. Il controllo di versione se lo ricorda. Un file pieno di blocchi commentati diventa presto inaffidabile.
• Salta l'ovvio. x = x + 1 # increment x non aggiunge nulla.

In sintesi

I commenti non costano niente da scrivere e poco da saltare. Usali quando lasci una nota per cui chi legge ti ringrazierà: il motivo sottile per cui qualcosa funziona, un link a una segnalazione, un avviso su un caso limite. Usa le docstring quando definisci una funzione o una classe. Per il resto, lascia parlare nomi chiari e funzioni piccole.

Ora hai tutto ciò che ti serve per leggere e scrivere un file Python. Il prossimo capitolo è quello in cui il linguaggio comincia davvero a fare cose: variabili, tipi di dati e i valori che Python può contenere.