Sebbene i commenti siano principalmente utili a chi lavora come developer<\/a>, scriverne di efficaci pu\u00f2 anche aiutare a produrre un’eccellente documentazione per gli utenti del vostro codice. Con l’aiuto di generatori di documenti come Sphinx<\/a> per progetti Python, i commenti nel codice possono fornire contenuti utili per la vostra documentazione.<\/p>\n Diamo un’occhiata ai commenti in Python.<\/p>\n Secondo la Python PEP 8 Style Guide<\/a>, ci sono diverse cose da tenere a mente quando si scrivono i commenti:<\/p>\n In Python, una riga \u00e8 dichiarata come commento quando inizia con il simbolo I commenti in linea forniscono brevi descrizioni di variabili e semplici operazioni e sono scritti sulla stessa riga della dichiarazione di codice:<\/p>\n Il commento spiega la funzione del codice nella stessa dichiarazione del codice.<\/p>\n 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 \u00e8 che i commenti a blocchi sono scritti su una riga separata:<\/p>\n 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\u00f9 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.<\/p>\n Python non supporta nativamente i commenti multilinea, il che significa che non ci sono disposizioni speciali per definirli. Nonostante ci\u00f2, i commenti che coprono pi\u00f9 righe sono molto utilizzati.<\/p>\n Potete creare un commento multilinea da pi\u00f9 commenti a riga singola anteponendo a ogni riga Potete anche usare la sintassi delle stringhe multilinea. In Python, potete definire le stringhe multilinea racchiudendole in 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:<\/p>\n 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.<\/p>\n In Python, le docstring sono commenti di pi\u00f9 righe che spiegano come usare una determinata funzione o classe. La documentazione del codice viene migliorata grazie alla creazione di docstring di alta qualit\u00e0. Quando si lavora con una funzione o una classe e si usa la funzione integrata Python PEP 257<\/a> fornisce un metodo standard per dichiarare le docstring in Python, come mostrato di seguito:<\/p>\n Nel codice qui sopra, la docstring fornisce dettagli sul funzionamento della funzione associata. Con i generatori di documentazione come Sphinx, questa docstring pu\u00f2 essere utilizzata per fornire agli utenti del vostro progetto una panoramica su come usare questo metodo.<\/p>\n Una docstring definita appena sotto la firma di una funzione o di una classe pu\u00f2 essere restituita anche utilizzando la funzione integrata La chiamata alla funzione L’attributo 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.<\/p>\n I commenti TODO non devono essere scritti come pseudocodice: devono solo spiegare brevemente la funzione del codice non ancora scritto.<\/p>\n I commenti TODO e i commenti di blocco a riga singola sono molto simili e l’unica differenza tra loro \u00e8 che i commenti TODO devono iniziare con il prefisso TODO:<\/p>\n \u00c8 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.<\/p>\n Esiste una serie di buone pratiche da seguire nella scrittura dei commenti per garantire affidabilit\u00e0 e qualit\u00e0. Di seguito sono riportati alcuni consigli per scrivere commenti di alta qualit\u00e0 in Python.<\/p>\n I commenti che affermano cose ovvie non aggiungono alcun valore al vostro codice e dovrebbero essere evitati. Ad esempio:<\/p>\n Questo commento non \u00e8 utile, perch\u00e9 si limita a dire cosa fa il codice senza spiegare il perch\u00e9. I commenti dovrebbero spiegare il “perch\u00e9” piuttosto che il “cosa” del codice che descrivono.<\/p>\n Riscritto in modo pi\u00f9 utile, l’esempio precedente potrebbe apparire come segue:<\/p>\n I commenti devono essere brevi e facilmente comprensibili. Dovrebbero essere scritti in prosa standard, non in pseudocodice, e dovrebbero sostituire la necessit\u00e0 di leggere il codice vero e proprio per avere una visione generale di ci\u00f2 che fa. Commenti troppo dettagliati o complessi non facilitano il lavoro di chi programma. Per esempio:<\/p>\n Il commento precedente fornisce pi\u00f9 informazioni di quelle necessarie al lettore. Invece di specificare la logica principale, i commenti dovrebbero fornire un riassunto generale del codice. Questo commento pu\u00f2 essere riscritto come:<\/p>\n Gli identificatori devono essere usati con attenzione nei commenti. Cambiare i nomi o i casi degli identificatori pu\u00f2 confondere il lettore. Esempio:<\/p>\n Il commento precedente cita Quando scrivete del codice, dovete rispettare il principio DRY (non ripetervi) ed evitare il principio WET (scrivete tutto due volte).<\/p>\n Questo vale anche per i commenti. Evitate di usare pi\u00f9 dichiarazioni per descrivere il vostro codice e cercate di unire i commenti che spiegano lo stesso codice in un unico commento. Tuttavia, \u00e8 importante fare attenzione quando unite i commenti: l’unione incauta di pi\u00f9 commenti pu\u00f2 dare origine a un commento enorme che viola le guide di stile ed \u00e8 difficile da seguire per il lettore.<\/p>\n Ricordate che i commenti devono ridurre il tempo di lettura del codice.<\/p>\n Nel codice qui sopra, i commenti sono inutilmente frammentati e possono essere uniti in un unico commento:<\/p>\n Assicuratevi che i commenti siano indentati allo stesso livello del codice che descrivono. Quando non lo sono, possono essere difficili da seguire.<\/p>\n Per esempio, questo commento non \u00e8 indentato o posizionato correttamente:<\/p>\n Pu\u00f2 essere riscritto come segue:<\/p>\n I commenti sono una componente importante per scrivere codice comprensibile. L’investimento che fate nello scrivere un commento \u00e8 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\u00f9 approfondite sul vostro codice.<\/p>\n In questo tutorial avete imparato di pi\u00f9 sui commenti in Python, compresi i vari tipi di commenti Python, quando usarli e le migliori pratiche da seguire per crearli.<\/p>\n Scrivere buoni commenti \u00e8 un’abilit\u00e0 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.<\/p>\n Quando tutto sar\u00e0 pronto per lanciare i vostri progetti Python, la piattaforma di Application Hosting<\/a> di Kinsta pu\u00f2 portare il vostro codice da GitHub al cloud<\/a> in pochi secondi.<\/p>\n","protected":false},"excerpt":{"rendered":" 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 …<\/p>\n","protected":false},"author":275,"featured_media":63631,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_kinsta_gated_content":false,"_kinsta_gated_content_redirect":"","footnotes":""},"tags":[25596],"topic":[26215],"class_list":["post-63630","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","tag-python","topic-python"],"yoast_head":"\nI Commenti in Python<\/h2>\n
\n
#<\/code>. Quando l’interprete Python incontra #<\/code> nel vostro codice, ignora tutto ci\u00f2 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.<\/p>\nCommenti in Linea<\/h3>\n
border = x + 10 # Make offset of 10px<\/code><\/pre>\nCommenti a Blocchi<\/h3>\n
import csv\nfrom itertools import groupby\n\n# Get a list of names in a sequence from the csv file\nwith open('new-top-firstNames.csv') as f:\n file_csv = csv.reader(f)\n\n# Skip the header part: (sr, name, perc)\nheader = next(file_csv)\n \n# Only name from (number, name, perc)\npersons = [ x[1] for x in file_csv]\n\n# Sort the list by first letter because\n# The groupby function looks for sequential data.\npersons.sort(key=lambda x:x[0])\ndata = groupby(persons, key=lambda x:x[0])\n\n# Get every name as a list\ndata_grouped = {}\nfor k, v in data:\n\t# Get data in the form\n\t# {'A' : [\"Anthony\", \"Alex\"], \"B\" : [\"Benjamin\"]}\n\tdata_grouped[k] = list(v)<\/code><\/pre>\nCommenti a Pi\u00f9 Righe<\/h3>\n
#<\/code>:<\/p>\n# interpreter\n# ignores\n# these lines<\/code><\/pre>\n\"\"\"<\/code>, tripli apici doppi, o '''<\/code>, tripli apici singoli:<\/p>\nprint(\"Multi-Line Comment\")\n\"\"\"\nThis\nString is\nMulti line\n\"\"\"<\/code><\/pre>\nMulti-Line Comment<\/code><\/pre>\n\nCommenti Speciali<\/h2>\n
Commenti Docstring in Python<\/h3>\n
help(obj)<\/code>, le docstring possono essere utili per fornire una panoramica dell’oggetto.<\/p>\nfrom collections import namedtuple\nPerson = namedtuple('Person', ['name', 'age'])\n\n def get_person(name, age, d=False):\n \"\"\"\nReturns a namedtuple(\"name\", \"age\") object.\nAlso returns dict('name', 'age') if arg `d` is True\n\nArguments:\nname \u2013 first name, must be string\nage \u2013 age of person, must be int\nd \t\u2013 to return Person as `dict` (default=False)\n\n\"\"\"\np = Person(name, age)\nif d:\n return p._asdict()\nreturn p<\/code><\/pre>\nhelp()<\/code>. La funzione help()<\/code> 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)<\/code> pu\u00f2 essere chiamata per rivelare i docstring associati alla funzione get_person<\/code>. Se eseguite il codice qui sopra in una shell interattiva utilizzando il flag -i<\/code>, potete vedere come questa docstring verr\u00e0 analizzata da Python. Eseguite il codice precedente digitando python -i file.py<\/code>.<\/p>\n![\"Screenshot:](\"https:\/\/kinsta.com\/wp-content\/uploads\/2022\/12\/parsing-python-docstrings-on-command-line.png\")
help(get_person)<\/code> restituisce una docstring per la vostra funzione. L’output contiene get_person(name, age, d=False)<\/code>, che \u00e8 una firma di funzione che Python aggiunge automaticamente.<\/p>\nget_person.__ doc__<\/code> pu\u00f2 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)<\/code>. Tuttavia, \u00e8 improbabile che voi abbiate bisogno di modificare dinamicamente le docstring in fase di esecuzione in questo modo.<\/p>\nCommenti TODO<\/h3>\n
# TODO Get serialized data from the CSV file\n# TODO Perform calculations on the data\n# TODO Return to the user<\/code><\/pre>\nLe Migliori Pratiche per Scrivere Commenti in Python<\/h2>\n
Evitare i Commenti Ovvi<\/h3>\n
x = x + 4 # increase x by 4<\/code><\/pre>\nx = x + 4 # increase the border width<\/code><\/pre>\nI Commenti di Python Devono Essere Brevi<\/h3>\n
# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)\ndef get_area(r,h):\n\treturn (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\n# return area of cylinder\ndef get_area(r,h):\n\treturn (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\nUsare gli Identificatori con Attenzione<\/h3>\n
# return class() after modifying argument\ndef func(cls, arg):\n\treturn cls(arg+5)\n<\/code><\/pre>\nclass<\/code> e argument<\/code>, nessuno dei quali si trova nel codice. Questo commento pu\u00f2 essere riscritto come:<\/p>\n# return cls() after modifying arg\ndef func(cls, arg):\n\treturn cls(arg+5)<\/code><\/pre>\nDRY e WET<\/h3>\n
# function to do x work\ndef do_something(y):\n # x work cannot be done if y is greater than max_limit\n if y < 400:\n print('doing x work')<\/code><\/pre>\n# function to do x if arg:y is less than max_limit\ndef do_something(y):\n if y in range(400):\n print('doing x work')<\/code><\/pre>\nIndentazione Coerente<\/h3>\n
for i in range(2,20, 2):\n# only even numbers\n\tif verify(i):\n# i should be verified by verify()\n \tperform(x)<\/code><\/pre>\n# only even numbers\nfor i in range(2,20, 2):\n\t# i should be verified by verify()\n\tif verify(i):\n \tperform(x)<\/code><\/pre>\n\nRiepilogo<\/h2>\n