Crea commenti Python nel modo giusto

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

I commenti aiutano a spiegare il tuo codice Python ad altri programmatori e possono ricordarti perché hai fatto le scelte che hai fatto. I commenti semplificano il debug e la revisione del codice aiutando i futuri programmatori a comprendere le scelte di progettazione alla base del software.

Sebbene i commenti siano principalmente per gli sviluppatori, scriverne di efficaci può anche aiutare a produrre un'eccellente documentazione per gli utenti del tuo codice. Con l'aiuto di generatori di documenti come Sphinx per i progetti Python, i commenti nel tuo codice possono fornire contenuto per la tua documentazione.

Diamo un'occhiata sotto il cofano dei commenti in Python.

Commenti in Python

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

• I commenti dovrebbero essere sempre frasi complete e concise.
• È meglio non avere alcun commento piuttosto che uno difficile da capire o impreciso.
• I commenti dovrebbero essere aggiornati regolarmente per riflettere i cambiamenti nel tuo codice.
• Troppi commenti possono distrarre e ridurre la qualità del codice. I commenti non sono necessari dove lo scopo del codice è ovvio.

In Python, una riga viene dichiarata come commento quando inizia con il simbolo # . Quando l'interprete Python incontra # nel tuo codice, ignora qualsiasi cosa dopo quel simbolo e non produce alcun errore. Esistono due modi per dichiarare commenti a riga singola: commenti in linea e commenti di blocco.

Commenti in linea

I commenti incorporati forniscono brevi descrizioni di variabili e operazioni semplici e sono scritti sulla stessa riga dell'istruzione di codice:

 border = x + 10 # Make offset of 10px

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

Blocca commenti

I commenti di blocco vengono utilizzati per descrivere la logica complessa nel codice. I commenti di blocco in Python sono costruiti in modo simile ai commenti in linea — l'unica differenza è che i commenti di blocco 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)

Si noti che quando si utilizzano i commenti di blocco, i commenti vengono scritti sopra il codice che stanno spiegando. La Guida di stile PEP8 di Python stabilisce che una riga di codice non deve contenere più di settantanove caratteri e i commenti in linea spesso spingono le righe oltre questa lunghezza. Questo è il motivo per cui i commenti di blocco vengono scritti per descrivere il codice su righe separate.

Commenti su più righe

Python non supporta nativamente i commenti su più righe, il che significa che non esiste una disposizione speciale per definirli. Nonostante ciò, vengono spesso utilizzati commenti che si estendono su più righe.

È possibile creare un commento su più righe da più commenti su una sola riga facendo precedere ogni riga da # :

 # interpreter # ignores # these lines

Puoi anche utilizzare la sintassi delle stringhe su più righe. In Python, puoi definire stringhe multilinea racchiudendole tra """ , triple doppie virgolette o ''' , triple virgolette singole:

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

Nel codice sopra, la stringa multilinea non è assegnata a una variabile, il che fa funzionare la stringa 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 tuo codice, i commenti servono anche ad alcuni scopi speciali in Python, come pianificare future aggiunte di codice e generare documentazione.

Commenti Python Docstring

In Python, le docstring sono commenti su più righe che spiegano come utilizzare una determinata funzione o classe. La documentazione del tuo codice è migliorata dalla creazione di docstring di alta qualità. Mentre si lavora con una funzione o una classe e si utilizza la funzione help(obj) incorporata, le docstring potrebbero essere utili per fornire una panoramica dell'oggetto.

Python PEP 257 fornisce un metodo standard per dichiarare docstring in Python, 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 sopra, la docstring ha fornito dettagli su come funziona la funzione associata. Con generatori di documentazione come Sphinx, questa docstring può essere utilizzata per fornire agli utenti del tuo progetto una panoramica su come utilizzare questo metodo.

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

La chiamata alla funzione help(get_person) restituisce una docstring per la tua 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ò anche essere usato per recuperare e modificare le docstring a livello di programmazione. Dopo aver aggiunto "Alcune nuove informazioni" nell'esempio sopra, appare nella seconda chiamata a help(get_person) . Tuttavia, è improbabile che sia necessario modificare dinamicamente le docstring in fase di esecuzione in questo modo.

TODO Commenti

Durante la scrittura del codice, ci sono occasioni in cui vorrai evidenziare determinate righe o interi blocchi per migliorare. Queste attività sono contrassegnate dai commenti TODO. I commenti TODO sono utili quando si pianificano aggiornamenti o modifiche al codice o se si desidera informare gli utenti oi collaboratori del progetto che devono essere scritte sezioni specifiche del codice del file.

I commenti TODO non dovrebbero 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 un 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 il programmatore, l'interprete Python non visualizza i commenti TODO in modo diverso dai commenti di blocco.

Migliori pratiche durante la scrittura di commenti Python

Ci sono una serie di best practice che dovrebbero essere seguite quando si scrivono commenti per garantire affidabilità e qualità. Di seguito sono riportati alcuni suggerimenti per scrivere commenti di alta qualità in Python.

Evita l'ovvio

I commenti che affermano l'ovvio non aggiungono alcun valore al tuo codice e dovrebbero essere evitati. Per esempio:

 x = x + 4 # increase x by 4

Quel commento non è utile, poiché indica semplicemente cosa fa il codice senza spiegare perché deve essere fatto. I commenti dovrebbero spiegare il "perché" piuttosto che il "cosa" del codice che stanno descrivendo.

Riscritto in modo più utile, l'esempio sopra potrebbe assomigliare a questo:

 x = x + 4 # increase the border width

Mantieni i commenti di Python brevi e dolci

Mantieni i tuoi commenti brevi e facilmente comprensibili. Dovrebbero essere scritti in prosa standard, non in pseudocodice, e dovrebbero sostituire la necessità di leggere il codice effettivo per avere una panoramica generale di ciò che fa. Troppi dettagli o commenti complessi non facilitano il lavoro di un programmatore. 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 sopra fornisce più informazioni di quanto sia necessario per il lettore. Invece di specificare la logica di base, i commenti dovrebbero fornire un riepilogo 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)

Usa gli identificatori con attenzione

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

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

Il commento precedente menziona 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)

ASCIUTTO e UMIDO

Quando scrivi il codice, vuoi aderire al principio DRY (non ripeterti) ed evitare WET (scrivi tutto due volte).

Questo vale anche per i commenti. Evita di utilizzare più istruzioni per descrivere il tuo codice e prova a unire i commenti che spiegano lo stesso codice in un unico commento. Tuttavia, è importante fare attenzione quando si uniscono i commenti: l'unione incauta di più commenti può risultare in un commento enorme che viola le guide di stile ed è difficile da seguire per il lettore.

Ricorda che i commenti dovrebbero 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 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')

Rientro coerente

Assicurati che i commenti siano rientrati allo stesso livello del codice che stanno descrivendo. Quando non lo sono, possono essere difficili da seguire.

Ad esempio, questo commento non è rientrato 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 della scrittura di codice comprensibile. L'investimento che fai nello scrivere un commento è qualcosa che il tuo io futuro - o altri sviluppatori che hanno bisogno di lavorare sulla tua base di codice - apprezzeranno. I commenti ti consentono anche di ottenere informazioni più approfondite sul tuo codice.

In questo tutorial, hai imparato di più sui commenti in Python, inclusi i vari tipi di commenti Python, quando usarli e le migliori pratiche da seguire quando li crei.

Scrivere buoni commenti è un'abilità che deve essere studiata e sviluppata. Per esercitarti a scrivere commenti, considera di tornare indietro e aggiungere commenti ad alcuni dei tuoi progetti precedenti. Per ispirazione e per vedere le best practice in azione, dai un'occhiata ai progetti Python ben documentati su GitHub.

Quando sei pronto per rendere live i tuoi progetti Python, la piattaforma di hosting di applicazioni di Kinsta può trasferire il tuo codice da GitHub al cloud in pochi secondi.