Introduzione

Quando si scrive codice Python, è sempre buona norma rendere il codice pulito e facilmente comprensibile. Organizzare il codice, dare variabili e funzioni nomi descrittivi sono diversi modi per farlo.

Un altro modo per migliorare la leggibilità del codice è utilizzare i commenti. Un commento è una spiegazione o annotazione leggibile dall'uomo che viene utilizzata per spiegare il codice. Ad esempio, se hai scritto una regex complessa, aggiungi un commento che descrive cosa fa il codice.

I commenti aiutano anche altri sviluppatori a capire il tuo codice e il suo scopo.

I commenti dovrebbero essere brevi e pertinenti. Non spiegare qualcosa che è ovvio per il lettore.

Questo articolo tratta le basi per scrivere commenti in Python.

Scrivere commenti in Python

Python ignora tutto ciò che è scritto sulla riga dopo il segno hash (#).

I commenti possono essere aggiunti all'inizio sulla riga o in linea con altri codici:

# This is a Python comment.
print("Hello World") # This is an inline Python comment.

Lo spazio vuoto dopo il segno di hash non è obbligatorio, ma migliorerà la leggibilità del commento.

Un carattere hash all'interno di una stringa letterale non indica l'inizio di una riga di commento. È semplicemente un carattere hash:

paragraph = "# Hash inside quotes is not a comment."

I commenti dovrebbero essere allo stesso livello di rientro del codice sottostante:

def factorial(n):
  if n == 0:
    return 1
  else:
    # Use the factorial function
    return n * factorial(n-1)

Se l'editor di testo supporta l'evidenziazione della sintassi, i commenti sono generalmente rappresentati in verde.

I commenti sono utili anche durante il debug di uno script. Invece di eliminare alcune righe o blocchi, puoi commentarli:

# for fruit in fruits:
#   print(fruit)

Commenti multilinea in Python (Comment Blocks)

A differenza di altri comuni linguaggi di programmazione, Python supporta solo commenti a riga singola.

Il modo più semplice per scrivere commenti multilinea in Python è quello di aggiungere i commenti a riga singola uno dopo l'altro:

# This is the first line.
# This is the second line.

Un'altra opzione è usare docstrings.

Le docstring sono letterali di stringa multilinea che vengono utilizzate per documentare ciò che fa un modulo, una funzione, una classe o un metodo.

Una docstring inizia e termina con triple doppie virgolette (""") e può estendersi su una o più righe:

"""This is
a multiline
docstring.
"""

Docstrings non sono tecnicamente commenti. Quando un docstring si presenta come la prima istruzione in un modulo, funzione, classe o metodo, finisce nel bytecode e diventa l'attributo speciale __doc__ di quell'oggetto. Si consiglia di utilizzare regolarmente commenti hash a riga singola.

Shebang

Se stai leggendo script Python, potresti notare che su alcuni di essi la prima riga inizia con i caratteri #! e il percorso dell'interprete Python:

#!/usr/bin/env python3

Questa sequenza di caratteri viene chiamata shebang e viene utilizzata per indicare al sistema operativo quale interprete utilizzare per analizzare il resto del file. Gli script che iniziano con shebang e sono eseguibili possono essere eseguiti nel terminale senza digitare python prima del nome dello script.

Poiché la riga shebang inizia con il carattere hash, viene considerata come un commento e automaticamente ignorata dall'interprete Python.

Conclusione

Scrivere commenti è una buona pratica e aiuta altri sviluppatori, incluso il sé futuro, a capire cosa fa il codice. In Python, tutto ciò che segue il segno di hash (#) e fino alla fine della riga è considerato un commento.