Come commentare in Python

Aggiornato a luglio 2021

Introduzione

Un'abilità chiave nella scrittura del codice è la capacità di utilizzare i commenti. I commenti sono righe che compilatori e interpreti ignorano e che gli sviluppatori usano per lasciare note sulla funzione del codice. Inoltre, possono essere utilizzati anche per disabilitare parti del codice.

Questa guida ti mostrerà come utilizzare i commenti in Python in modo efficace.

Prerequisiti

• Un ambiente di programmazione Python funzionante
• La possibilità di creare e modificare file Python

Sintassi dei commenti Python

Per aggiungere o contrassegnare una riga come commento, inizia con un segno cancelletto (# ) e uno spazio :

# This is a sample comment.

L'uso del segno hash per iniziare la riga indica al sistema di ignorare tutto in quella riga. Quando l'applicazione viene eseguita, il programma fa finta che quelle righe non esistano. Tuttavia, puoi ancora vederlo quando modifichi il file.

Ad esempio, in Hello World programma di seguito:

# Display the text "Hello, World!" on the screen.
print("Hello, World!")

Il sistema esegue il codice print("Hello, World") nella riga quattro, mentre la riga sopra spiega cosa dovrebbe fare il codice.

Puoi impostare qualsiasi riga come commento e usarne quante ne vuoi. Se il tuo codice ha blocchi diversi, puoi usare un commento per spiegarli. Ad esempio:

# Define a variable flowers as a list of strings.
flowers = [‘rose’, ‘carnation’, ‘daisy’, ‘marigold’, ‘tulip’, ‘sunflower’]

# Create a for loop to iterate through flowers list, and displays each string item.
for flower in flowers:
            print(flower)

Blocco commenti Python

Blocca commenti sono commenti in formato più lungo costituiti da più righe di seguito. Uno sviluppatore li usa per spiegare codice più complesso, specialmente quando lavora in un team.

Per contrassegnare una serie di righe come commento, aggiungi un segno cancelletto + spazio all'inizio di ogni riga:

# This is a comment
# that runs on to
# multiple lines.

Alcuni editor di testo o codice per la programmazione (come Notepad++ o Atom) consentono di evidenziare il testo, quindi fare clic con il mouse per contrassegnare il blocco come commento. Questi strumenti possono farti risparmiare tempo commentando ogni riga.

Commento su più righe Python

In generale, si consiglia di utilizzare # all'inizio di ogni riga per contrassegnarla come commento. Tuttavia, commentare un'ampia sezione richiede molto tempo e potresti aver bisogno di un modo rapido per commentare un'intera sezione. In questi casi, puoi utilizzare commenti su più righe .

Le stringhe multilinea non funzionano come i tradizionali commenti Python, poiché non esiste una funzionalità multilinea ufficiale. Utilizza invece stringhe di più righe racchiuse tra virgolette triple (""" ) per ottenere una funzione simile.

Ad esempio:

def addition_test(a, b):
    result = a + b
    """
    This is a block
    of commented lines.
    They aren’t parsed and interpreted by the compiler.
    """
return result

Questo metodo crea una costante di testo senza funzione, non un vero commento. Finché non aggiungi nulla che acceda a quella stringa di testo, funziona come un normale commento.

Le virgolette triple possono essere complicate perché in alcune circostanze crea una docstring se una virgoletta tripla:

• segue una firma di funzione,
• segue una definizione di classe,
• è all'inizio di un modulo.

Se inserisci """ in uno dei luoghi sopra elencati, Python lo legge come un dosctring . Docstrings ti consente di inserire testo leggibile dall'uomo nel progetto. Di solito viene utilizzato per creare documentazione che fa parte dell'applicazione e a cui è possibile accedere in fase di esecuzione.

Commento in linea Python

Puoi commentare nella stessa riga di un pezzo di codice utilizzando un commento in linea . Il momento migliore per utilizzare questa opzione è quando si spiega un'operazione complicata.

Usa un commento in linea per indicare il punto esatto che vuoi chiarire. Aggiungi il segno cancelletto standard + spazio per indicare un commento in linea:

function
    set variable
    run command
    run additional command        # Tricky part:  The program breaks if this line is removed.

I commenti in linea vengono utilizzati per aggiungere contesto alle persone che leggono il codice. Ad esempio, potresti spiegare lo scopo di una variabile o lasciare una nota sul tipo di variabile creata. Può anche essere utile spiegare perché viene utilizzato un particolare comando, come nell'esempio sopra.

Commento Python in uscita

Poiché i commenti rendono il testo invisibile al parser, puoi usarli per disabilitare i comandi. In questo modo puoi testare segmenti di codice con e senza nuove aggiunte.

Ad esempio, in questo semplice programma di lancio dei dadi, c'è una sezione commentata. Se rimuovi il segno hash, abiliti il ​​codice per testarlo.

import random
min = 1
max = 6

roll_again = "yes"

while roll_again == "yes" or roll_again == "y":
     print "Rolling the dice..."
     print "The values are...."
     print random.randint(min, max)
     print random.randint(min, max)

# Add two random numbers together for a sum
# while roll_again == “yes” or roll_again == “y”:
    # print ”Rolling the dice…”
    # print “You rolled a “
    # print random.randint(min,max) + random.randint(min, max)

    roll_again = raw_input("Roll the dice again?")

Perché i commenti sono importanti in Python

Commentare può aiutarti:

• Comprendi il tuo codice quando torni ad esso dopo un periodo di tempo più lungo.
• Fai tornare a correre più velocemente.
• Problemi di debug.
• Comprendi alcune scelte di codice quando lavori all'interno di un team.
• Previeni potenziali problemi sottolineando il motivo per cui una parte di codice specifica è importante.

Il codice Python commenta le migliori pratiche

• Commenta con lo stesso rientro del codice a cui ti riferisci. In questo modo è più facile vedere a cosa ti riferisci.
• Aggiorna i tuoi commenti quando aggiorni il codice. I commenti errati sono peggio di nessun commento.
• Usa frasi complete. Scrivi in ​​maiuscolo le parole appropriate, a meno che non ti riferisci a un identificatore (come una variabile). Non modificare mai le maiuscole e minuscole di un identificatore.
• I commenti in blocco devono essere scritti in frasi complete, con punti. Punta a 80 parole per riga o meno.
• Se hai più frasi in un commento, usa uno spazio doppio tra le frasi.
• Scrivi commenti in inglese.
• Per un commento in blocco con più paragrafi, aggiungi una riga vuota tra i paragrafi con un singolo tag di commento che precede una riga vuota.
• Per i commenti in linea, lascia almeno due spazi tra il codice e il commento. Usa i commenti in linea con parsimonia ed evita di usarli per affermare l'ovvio.

EVITARE:

• Non commentare il codice che si spiega da sé. Attieniti al principio di scrivere DRY (D su non R ripeti S noi stessi) ed evitare WET (C rito E tutto T wice) codice e commenti.
• Evita di usare i commenti per spiegare il codice disordinato:i commenti dovrebbero supportare il codice e non giustificarlo.