Scrivere buoni commenti in Python consentirà ad altri sviluppatori e tester di leggere e comprendere facilmente il tuo codice.
Il codice pulito con sintassi coerente, denominazione variabile descrittiva e rientro è come il primo libro, più facile da comprendere e mantenere.
Inoltre, al giorno d’oggi, è meno comune per un individuo scrivere il codice completo per l’intera applicazione o software; piuttosto, una squadra o un gruppo di persone lavorerà per lo stesso obiettivo. In questo caso, un codice pulito e leggibile rende la collaborazione più semplice ed efficiente.
Gli sviluppatori e i tester mirano sempre a distribuire software privo di bug in produzione. La scrittura di codice pulito e leggibile accelera questo processo rendendo il debug più semplice e accurato. Anche se trovi alcuni errori nella produzione, il codice più pulito è più facile da aggiornare.
Ancora più importante, il codice pulito e leggibile dura più a lungo perché rimane aggiornato col passare del tempo.
Infine, è fondamentale disporre di un codice pulito e leggibile per creare software di lunga durata. Ma la domanda è: come possiamo raggiungere esattamente questo obiettivo? Bene, un metodo sta usando i commenti.
Non è frustrante quando hai scritto l’intero codice per una logica complessa, ma il giorno dopo, quando non puoi riprendere da dove avevi interrotto? Questo non succede quando scrivi commenti.
I commenti sono un linguaggio umano che spiega cosa sta facendo il codice sorgente. Puoi scriverli in qualsiasi lingua, preferibilmente in inglese, poiché è una lingua globale.
Quindi, ogni volta che torni al tuo codice sorgente dopo giorni o addirittura anni, i commenti ti spiegheranno cosa hai scritto una volta.
Inoltre, aiutano altri sviluppatori a comprendere facilmente il tuo codice. Ecco perché il codice scritto con i commenti resta per sempre, anche in assenza del suo autore.
Inoltre, è abbastanza comune avere conflitti quando si ha a che fare con linguaggi di programmazione diversi, soprattutto quando si lavora in gruppo. È qui che i commenti vengono in soccorso. Anche se non conosci il linguaggio di programmazione del codice sorgente scritto dal tuo compagno di squadra, i commenti ti aiutano a comprenderne la logica.
La documentazione del codice è un modo più completo per mantenere il codice sorgente e consente al tuo team di collaborare senza problemi. Contiene tutto ciò che riguarda il codice, come design, funzionalità, architettura, componenti, ecc.,
I commenti contribuiscono anche alla documentazione di questo codice. I commenti ben scritti possono essere inseriti direttamente nella documentazione del codice in modo che gli sviluppatori non solo ottengano il cosa e il perché, ma anche il come del tuo codice.
- I commenti non si limitano a leggere il codice ma ti aiutano anche a comprendere l’intento dello sviluppatore dietro ogni riga. Quindi se trovi qualche bug in futuro, saprai dove effettuare esattamente gli aggiornamenti del codice.
- Puoi scrivere commenti come un paragrafo per l’intero codice o singole righe che spiegano cosa fa ciascun blocco di codice. In questo modo, consentono a te e agli altri sviluppatori di comprendere bene il codice, migliorandone la leggibilità.
- I commenti possono dividere il codice in sezioni logiche, semplificando la navigazione nel codice.
- Dovresti includere commenti che descrivono in dettaglio input, output e casi d’uso previsti in modo che un tester possa leggere il tuo codice.
- Infine, inserire commenti ben scritti nella documentazione migliora la leggibilità complessiva della documentazione del codice.
I commenti in Python iniziano con il simbolo cancelletto (#). Pertanto, quando inizi una riga con il cancelletto (#), qualsiasi cosa scritta in quella riga viene trattata come un commento.
Quando esegui il codice, il compilatore ignora la riga che inizia con l’hash (#) come se non esistesse nemmeno. Tuttavia, i commenti rimangono visibili nel codice sorgente per servire al loro scopo.
Ci sono tre tipi principali.
Questi sono quelli che hai visto sopra. Iniziano con il simbolo cancelletto (#). Fondamentalmente la riga che inizia con il simbolo cancelletto (#) è dedicata al commento. Quindi, questo è chiamato commento a riga singola, in cui puoi scrivere un commento solo su una riga che inizia con l’hash (#).
Ecco come scrivere commenti su una sola riga
# This is single line comment.
Tecnicamente, Python non supporta i commenti su più righe, ma ci sono modi per ottenere ciò in Python.
È possibile utilizzare l’hash (#) anche per scrivere commenti su più righe. Ogni riga che scrivi dovrebbe iniziare con un simbolo cancelletto (#) qui.
# This is the first comment. # This is second comment. # This is the last comment.
Sommario:
#3. Stringhe di documenti Python
Un modo popolare per scrivere commenti su più righe è utilizzare stringhe letterali: “””….”””. Quando scrivi qualcosa tra virgolette triple, il compilatore Python ignora quelle righe ed esegue la parte rimanente nel file.
Questi commenti sono chiamati docstring se scritti subito dopo le funzioni, i moduli e le classi.
Ecco la sintassi per farlo
""" Multi-line comments using docstrings in Python. """
Scrivere commenti chiari e dettagliati migliora la leggibilità e la manutenzione del codice. Quindi, ecco le migliori pratiche per commentare in modo chiaro in Python.
I commenti non dovrebbero limitarsi a narrare cosa sta facendo il codice, ma dovrebbero riflettere lo scopo e l’intento dietro ogni riga.
Rimuovi i commenti obsoleti e assicurati di aggiornare i commenti ogni volta che modifichi il codice.
Invece di storie lunghe, scrivi commenti brevi e mirati.
Bad example: The function takes a,b as input, calculates a + b, and returns the value. Good example: The function returns the sum of a and b.
L’uso di nomi significativi e descrittivi per le variabili e i nomi delle funzioni può eliminare i commenti ridondanti.
Prima il codice? O commentare prima? Commentare prima della codifica è la pratica migliore; cioè scrivi i tuoi commenti e poi il codice corrispondente. In questo modo puoi prima pensare alla logica e poi convertirla in codice.
# Returns true if the cnt is less than 1. return cnt < 1
Utilizza un formato di commento coerente come spaziatura, rientro, tipo di commenti, ecc., per l’intero codice. Ciò creerà meno confusione e sarà più organizzato per i lettori.
Utilizza le docstring per spiegare funzioni e classi in Python come mostrato nell’esempio seguente.
def add_num(a,b):
""" this function returns the sum of a and b """
sum = a+b
return sum
Evita commenti non necessari nel tuo codice. Ad esempio, la seguente riga di codice non necessita di commenti per essere compresa.
ans = 42
#1. Editor di codice di Visual Studio
Editor di codice di Visual Studio è il miglior IDE creato da Microsoft per un ambiente di sviluppo completo. Con il supporto nativo per Node.js e JavaScript, lo strumento supporta perfettamente anche molti altri linguaggi di programmazione.
Questo strumento altamente personalizzabile ha varie estensioni per diverse funzionalità. “Better Comments” è una di queste estensioni che ti consente di creare commenti a misura d’uomo.
Puoi classificare i tuoi commenti in avvisi, domande, evidenziazioni, ecc., per una navigazione più semplice.
Il codice VS supporta la modifica di più cursori in modo da poter commentare o modificare più righe contemporaneamente.
Questo editor è disponibile su tutte le principali piattaforme come Mac, Windows e Linux.
#2. Testo sublime
Testo sublime è l’editor di riferimento per grandi progetti e codifica pesante. L’editor è noto per la sua velocità, personalizzazione e scorciatoie.
La potente funzionalità di evidenziazione della sintassi dello strumento ti aiuta a distinguere facilmente tra codice e commenti.
Come il codice VS, il testo Sublime supporta anche la modifica multi-cursore per commentare più righe contemporaneamente.
Grazie alla sua funzione di completamento automatico. Non è necessario ripetere manualmente le righe di codice; questa funzione completa automaticamente il tuo codice in base ai modelli, aiutandoti a codificare più velocemente.
Inoltre, la funzione “Vai a qualsiasi cosa” dello strumento ti consente di passare facilmente da una funzione all’altra e da un file all’altro del tuo progetto.
#3. Blocco note++
Blocco nodi++ è un editor di testo popolare e semplice scritto in C++ e supporta numerosi linguaggi di programmazione. Non sembra un editor moderno come VS Code o Sublime Text; la sua interfaccia è molto semplice e sembra che faccia ciò che deve.
Nodepad++ offre numerose scorciatoie standard per commenti efficienti. Puoi anche personalizzare la tastiera di scelta rapida per personalizzare la tua esperienza di commento.
La sua funzione di mappatura dei documenti ti mostra la panoramica della struttura del progetto, permettendoti di navigare tra file, cartelle e codice senza problemi.
#4. Vim
Vim L’IDE fornisce uno sviluppo e un’esecuzione del codice più rapidi. Tutto e qualsiasi cosa può essere fatto su questo editor usando le scorciatoie da tastiera, quindi dovresti impegnarti seriamente per padroneggiarlo.
Questo editor incentrato sulla tastiera offre anche molte funzionalità di commento tramite scorciatoie da tastiera. Ha potenti funzionalità e comandi per navigare in modo efficace tra i commenti.
Questo software leggero può gestire file di grandi dimensioni e centinaia di linguaggi di programmazione. Chi odia le cose gratis? Come tutti gli editor presenti nell’elenco, anche Vim è completamente gratuito e open source.
È nativo nei sistemi macOS e Linux ed è scaricabile su Windows.
#5. PyCharm
PyCharm è un potente IDE appositamente progettato per lo sviluppo Python. Sebbene supporti molti altri linguaggi di programmazione, funziona meglio per Python. Dispone di completamento del codice, evidenziazione della sintassi e funzionalità di debug su misura per Python.
Inoltre, rende i commenti in Python molto più efficienti. Fornisce funzionalità di navigazione per aiutarti a passare facilmente a commenti specifici.
Ottieni vari modelli di commenti e crea modelli di commenti personalizzati in modo efficiente in Pycharm.
Inoltre, gli strumenti di refactoring dell’editor ti consentono di aggiornare o correggere facilmente i commenti.
Conclusione
Seguire gli standard del codice è necessario durante l’intero processo di sviluppo del codice ed è obbligatorio per scrivere codice pronto per la produzione, poiché il codice dovrebbe essere leggibile da tutti gli altri sviluppatori e tester.
Una pratica importante per creare un codice leggibile è scrivere commenti. I commenti sono disponibili in quasi tutti i linguaggi di programmazione. Tuttavia, con questo articolo, ora dovresti sapere come scrivere commenti Python, i loro tipi e le migliori pratiche da seguire durante la scrittura dei commenti.
Inoltre, sono elencati di seguito i migliori editor di codice che ti aiutano nella gestione dei commenti.