I commenti sono note che programmatrici e programmatori aggiungono al loro codice per spiegare cosa deve fare quel codice. I compilatori o gli interpreti che trasformano il codice in azioni ignorano i commenti, ma possono essere essenziali per la gestione dei progetti software.

I commenti servono a spiegare il vostro codice Python ad altri programmatori ma possono essere utili anche a voi per ricordare perché avete fatto determinate scelte. I commenti facilitano il debug e la revisione del codice, aiutando i futuri programmatori a comprendere le scelte progettuali alla base del software.

Sebbene i commenti siano principalmente utili a chi lavora come developer, scriverne di efficaci può anche aiutare a produrre un’eccellente documentazione per gli utenti del vostro codice. Con l’aiuto di generatori di documenti come Sphinx per progetti Python, i commenti nel codice possono fornire contenuti utili per la vostra documentazione.

Diamo un’occhiata ai commenti in Python.

I Commenti in Python

Secondo la Python PEP 8 Style Guide, ci sono diverse cose da tenere a mente quando si scrivono i commenti:

  • I commenti devono essere sempre frasi complete e concise.
  • È meglio non avere alcun commento piuttosto che uno difficile da capire o impreciso.
  • I commenti devono essere aggiornati regolarmente per riflettere le modifiche apportate al codice.
  • Troppi commenti possono distrarre e ridurre la qualità del codice. I commenti non sono necessari quando lo scopo del codice è ovvio.

In Python, una riga è dichiarata come commento quando inizia con il simbolo #. Quando l’interprete Python incontra # nel vostro codice, ignora tutto ciò che segue questo simbolo e non produce alcun errore. Esistono due modi per dichiarare commenti su una sola riga: i commenti in linea e i commenti a blocchi.

Commenti in Linea

I commenti in linea forniscono brevi descrizioni di variabili e semplici operazioni e sono scritti sulla stessa riga della dichiarazione di codice:

border = x + 10  # Make offset of 10px

Il commento spiega la funzione del codice nella stessa dichiarazione del codice.

Commenti a Blocchi

I commenti a blocchi sono utilizzati per descrivere la logica complessa del codice. I commenti a blocchi in Python sono costruiti in modo simile ai commenti in linea: l’unica differenza è che i commenti a blocchi sono scritti su una riga separata:

import csv
from itertools import groupby

# Get a list of names in a sequence from the csv file
with open('new-top-firstNames.csv') as f:
    file_csv = csv.reader(f)

# Skip the header part: (sr, name, perc)
header = next(file_csv)
    
# Only name from (number, name, perc)
persons = [ x[1] for x in file_csv]

# Sort the list by first letter because
# The groupby function looks for sequential data.
persons.sort(key=lambda x:x[0])
data = groupby(persons, key=lambda x:x[0])

# Get every name as a list
data_grouped = {}
for k, v in data:
	# Get data in the form
	# {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]}
	data_grouped[k] = list(v)

Notate che quando si usano i commenti a blocchi, questi vengono scritti sopra il codice che stanno spiegando. La Guida allo stile di Python PEP8 stabilisce che una riga di codice non deve contenere più di settantanove caratteri e i commenti in linea spesso superano questa lunghezza. Per questo motivo i commenti a blocchi vengono scritti per descrivere il codice su righe separate.

Commenti a Più Righe

Python non supporta nativamente i commenti multilinea, il che significa che non ci sono disposizioni speciali per definirli. Nonostante ciò, i commenti che coprono più righe sono molto utilizzati.

Potete creare un commento multilinea da più commenti a riga singola anteponendo a ogni riga #:

# interpreter
# ignores
# these lines

Potete anche usare la sintassi delle stringhe multilinea. In Python, potete definire le stringhe multilinea racchiudendole in """, tripli apici doppi, o ''', tripli apici singoli:

print("Multi-Line Comment")
"""
This
String is
Multi line
"""

Nel codice qui sopra, la stringa multilinea non viene assegnata a una variabile, per cui la stringa funziona come un commento. In fase di esecuzione, Python ignora la stringa e non viene inclusa nel bytecode. L’esecuzione del codice precedente produce il seguente output:

Multi-Line Comment

Commenti Speciali

Oltre a rendere leggibile il vostro codice, i commenti hanno anche alcune funzioni speciali in Python, come la pianificazione di future aggiunte di codice e la generazione di documentazione.

Commenti Docstring in Python

In Python, le docstring sono commenti di più righe che spiegano come usare una determinata funzione o classe. La documentazione del codice viene migliorata grazie alla creazione di docstring di alta qualità. Quando si lavora con una funzione o una classe e si usa la funzione integrata help(obj), le docstring possono essere utili per fornire una panoramica dell’oggetto.

Python PEP 257 fornisce un metodo standard per dichiarare le docstring in Python, come mostrato di seguito:

from collections import namedtuple
Person = namedtuple('Person', ['name', 'age'])

 def get_person(name, age, d=False):
    """
Returns a namedtuple("name", "age") object.
Also returns dict('name', 'age') if arg `d` is True

Arguments:
name  – first name, must be string
age   – age of person, must be int
d 	– to return Person as `dict` (default=False)

"""
p = Person(name, age)
if d:
    return p._asdict()
return p

Nel codice qui sopra, la docstring fornisce dettagli sul funzionamento della funzione associata. Con i generatori di documentazione come Sphinx, questa docstring può essere utilizzata per fornire agli utenti del vostro progetto una panoramica su come usare questo metodo.

Una docstring definita appena sotto la firma di una funzione o di una classe può essere restituita anche utilizzando la funzione integrata help(). La funzione help() accetta come argomento il nome di un oggetto o di una funzione e restituisce come output le docstring della funzione. Nell’esempio precedente, help(get_person) può essere chiamata per rivelare i docstring associati alla funzione get_person. Se eseguite il codice qui sopra in una shell interattiva utilizzando il flag -i, potete vedere come questa docstring verrà analizzata da Python. Eseguite il codice precedente digitando python -i file.py.

Screenshot: Commenti della docstring Python analizzati nel terminale.
I commenti della docstring Python analizzati nell’interfaccia a riga di comando.

La chiamata alla funzione help(get_person) restituisce una docstring per la vostra funzione. L’output contiene get_person(name, age, d=False), che è una firma di funzione che Python aggiunge automaticamente.

L’attributo get_person.__ doc__ può essere utilizzato anche per recuperare e modificare le docstring in modo programmatico. Dopo aver aggiunto “Qualche altra nuova informazione” nell’esempio precedente, appare nella seconda chiamata a help(get_person). Tuttavia, è improbabile che voi abbiate bisogno di modificare dinamicamente le docstring in fase di esecuzione in questo modo.

Commenti TODO

Quando scrivete del codice, ci sono occasioni in cui vorrete evidenziare alcune righe o interi blocchi da migliorare. Questi compiti sono segnalati dai commenti TODO. I commenti TODO sono utili quando state pianificando aggiornamenti o modifiche al vostro codice, oppure se volete informare gli utenti o i collaboratori del progetto che alcune sezioni specifiche del codice del file devono ancora essere scritte.

I commenti TODO non devono essere scritti come pseudocodice: devono solo spiegare brevemente la funzione del codice non ancora scritto.

I commenti TODO e i commenti di blocco a riga singola sono molto simili e l’unica differenza tra loro è che i commenti TODO devono iniziare con il prefisso TODO:

# TODO Get serialized data from the CSV file
# TODO Perform calculations on the data
# TODO Return to the user

È importante notare che, sebbene molti IDE possano evidenziare questi commenti per chi programma, l’interprete Python non considera i commenti TODO in modo diverso dai commenti a blocchi.

Le Migliori Pratiche per Scrivere Commenti in Python

Esiste una serie di buone pratiche da seguire nella scrittura dei commenti per garantire affidabilità e qualità. Di seguito sono riportati alcuni consigli per scrivere commenti di alta qualità in Python.

Evitare i Commenti Ovvi

I commenti che affermano cose ovvie non aggiungono alcun valore al vostro codice e dovrebbero essere evitati. Ad esempio:

x = x + 4 # increase x by 4

Questo commento non è utile, perché si limita a dire cosa fa il codice senza spiegare il perché. I commenti dovrebbero spiegare il “perché” piuttosto che il “cosa” del codice che descrivono.

Riscritto in modo più utile, l’esempio precedente potrebbe apparire come segue:

x = x + 4 # increase the border width

I Commenti di Python Devono Essere Brevi

I commenti devono essere brevi e facilmente comprensibili. Dovrebbero essere scritti in prosa standard, non in pseudocodice, e dovrebbero sostituire la necessità di leggere il codice vero e proprio per avere una visione generale di ciò che fa. Commenti troppo dettagliati o complessi non facilitano il lavoro di chi programma. Per esempio:

# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)
def get_area(r,h):
	return (2*3.14*r*h) + (2*3.14*r*r)

Il commento precedente fornisce più informazioni di quelle necessarie al lettore. Invece di specificare la logica principale, i commenti dovrebbero fornire un riassunto generale del codice. Questo commento può essere riscritto come:

# return area of cylinder
def get_area(r,h):
	return (2*3.14*r*h) + (2*3.14*r*r)

Usare gli Identificatori con Attenzione

Gli identificatori devono essere usati con attenzione nei commenti. Cambiare i nomi o i casi degli identificatori può confondere il lettore. Esempio:

# return class() after modifying argument
def func(cls, arg):
	return cls(arg+5)

Il commento precedente cita class e argument, nessuno dei quali si trova nel codice. Questo commento può essere riscritto come:

# return cls() after modifying arg
def func(cls, arg):
	return cls(arg+5)

DRY e WET

Quando scrivete del codice, dovete rispettare il principio DRY (non ripetervi) ed evitare il principio WET (scrivete tutto due volte).

Questo vale anche per i commenti. Evitate di usare più dichiarazioni per descrivere il vostro codice e cercate di unire i commenti che spiegano lo stesso codice in un unico commento. Tuttavia, è importante fare attenzione quando unite i commenti: l’unione incauta di più commenti può dare origine a un commento enorme che viola le guide di stile ed è difficile da seguire per il lettore.

Ricordate che i commenti devono ridurre il tempo di lettura del codice.

# function to do x work
def do_something(y):
    # x work cannot be done if y is greater than max_limit
    if y < 400:
      print('doing x work')

Nel codice qui sopra, i commenti sono inutilmente frammentati e possono essere uniti in un unico commento:

# function to do x if arg:y is less than max_limit
def  do_something(y):
    if y in range(400):
        print('doing x work')

Indentazione Coerente

Assicuratevi che i commenti siano indentati allo stesso livello del codice che descrivono. Quando non lo sono, possono essere difficili da seguire.

Per esempio, questo commento non è indentato o posizionato correttamente:

for i in range(2,20, 2):
# only even numbers
	if verify(i):
# i should be verified by verify()
    	perform(x)

Può essere riscritto come segue:

# only even numbers
for i in range(2,20, 2):
	# i should be verified by verify()
	if verify(i):
    	perform(x)

Riepilogo

I commenti sono una componente importante per scrivere codice comprensibile. L’investimento che fate nello scrivere un commento è un investimento che il vostro io futuro o altre persone che devono lavorare sul vostro codice apprezzeranno. Inoltre, i commenti vi permettono di ottenere informazioni più approfondite sul vostro codice.

In questo tutorial avete imparato di più sui commenti in Python, compresi i vari tipi di commenti Python, quando usarli e le migliori pratiche da seguire per crearli.

Scrivere buoni commenti è un’abilità che va studiata e sviluppata. Per esercitarvi a scrivere commenti, considerate di tornare indietro e aggiungere commenti ad alcuni dei vostri progetti precedenti. Per trovare ispirazione e vedere le migliori pratiche in azione, date un’occhiata ai progetti Python ben documentati su GitHub.

Quando tutto sarà pronto per lanciare i vostri progetti Python, la piattaforma di Application Hosting di Kinsta può portare il vostro codice da GitHub al cloud in pochi secondi.

Vivek Singh

Vivek is a Python and Django developer who's always ready to learn and teach new things to fellow developers.