Qual è il modo corretto di commentare le funzioni in Python?

Esiste un modo generalmente accettato per commentare le funzioni in Python? È accettabile la seguente?

#########################################################
# Create a new user
#########################################################
def add(self):

Il modo corretto per farlo è fornire una dotstring. In questo modo, help(add)sputerà anche il tuo commento.

def add(self):
    """Create a new user.
    Line 2 of comment...
    And so on... 
    """

Sono tre virgolette doppie per aprire il commento e altre tre virgolette doppie per terminarlo. Puoi anche usare qualsiasi stringa Python valida. Non deve essere multilinea e le doppie virgolette possono essere sostituite da virgolette singole.

Vedi: PEP 257

Usa una dotstring, come altri hanno già scritto.

Puoi anche fare un ulteriore passo avanti e aggiungere un doctest al tuo docstring, rendendo il test automatico delle tue funzioni un gioco da ragazzi.

Usa una dotstring :

Una stringa letterale che si presenta come la prima istruzione in una definizione di modulo, funzione, classe o metodo. Tale dotstring diventa l' __doc__attributo speciale di quell'oggetto.

Tutti i moduli dovrebbero normalmente avere dotstring e anche tutte le funzioni e le classi esportate da un modulo dovrebbero avere dotstring. Anche i metodi pubblici (incluso il __init__costruttore) dovrebbero avere dotstring. Un pacchetto può essere documentato nella documentazione del modulo del __init__.pyfile nella directory del pacchetto.

I letterali di stringa che si verificano altrove nel codice Python possono anche fungere da documentazione. Non sono riconosciuti dal compilatore bytecode Python e non sono accessibili come attributi di oggetti di runtime (cioè non assegnati a __doc__), ma due strumenti aggiuntivi possono essere estratti da strumenti software:

1. I letterali di stringa che si verificano immediatamente dopo una semplice assegnazione al livello più alto di un modulo, classe o __init__metodo sono chiamati "dotstrings dell'attributo".
2. I letterali di stringa che si verificano immediatamente dopo un'altra docstring sono chiamati "dotstring aggiuntivi".

Si prega di consultare PEP 258 , "Docutils Design Specification" [2] , per una descrizione dettagliata dell'attributo e ulteriori documenti ...

I principi del buon commento sono abbastanza soggettivi, ma ecco alcune linee guida:

• I commenti sulle funzioni dovrebbero descrivere l' intento di una funzione, non l'implementazione
• Descrivi tutti i presupposti che la tua funzione fa riguardo allo stato del sistema. Se utilizza variabili globali (tsk, tsk), elencale.
• Fai attenzione all'eccessiva arte ASCII . Avere lunghe stringhe di hash può sembrare che i commenti siano più facili da leggere, ma possono essere noiosi da gestire quando i commenti cambiano
• Sfrutta le funzionalità del linguaggio che forniscono "documentazione automatica", ovvero docstring in Python, POD in Perl e Javadoc in Java

Leggi informazioni sull'utilizzo di docstring nel tuo codice Python.

Secondo le convenzioni di docstring di Python :

Il docstring per una funzione o metodo dovrebbe riassumere il suo comportamento e documentare i suoi argomenti, i valori di ritorno, gli effetti collaterali, le eccezioni sollevate e le restrizioni su quando può essere chiamato (tutto se applicabile). Argomenti opzionali dovrebbero essere indicati. Dovrebbe essere documentato se gli argomenti di parole chiave fanno parte dell'interfaccia.

Non ci sarà alcuna regola d'oro, ma piuttosto fornire commenti che significhino qualcosa per gli altri sviluppatori del tuo team (se ne hai uno) o anche per te stesso quando torni ad esso sei mesi lungo la strada.

Vorrei andare per una pratica di documentazione che si integra con uno strumento di documentazione come Sphinx .

Il primo passo è usare un docstring:

def add(self):
 """ Method which adds stuff
 """

Vorrei fare un passo oltre il semplice dire "usa una dotstring". Scegli uno strumento di generazione della documentazione, come pydoc o epydoc (utilizzo epydoc in pyparsing) e usa la sintassi di markup riconosciuta da quello strumento. Esegui spesso questo strumento mentre stai sviluppando, per identificare buchi nella tua documentazione. In effetti, potresti persino trarre vantaggio dalla scrittura dei documenti per i membri di una classe prima di implementare la classe.

Usa dotstrings .

Questa è la convenzione suggerita integrata in PyCharm per i commenti sulla descrizione della funzione:

def test_function(p1, p2, p3):
    """
    my function does blah blah blah

    :param p1: 
    :param p2: 
    :param p3: 
    :return: 
    """

Mentre sono d'accordo che questo non dovrebbe essere un commento, ma una dotstring come la maggior parte (tutte?) Le risposte suggeriscono, voglio aggiungere numpydoc (una guida di stile di dotstring ) .

Se lo fai in questo modo, puoi (1) generare automaticamente documentazione e (2) le persone lo riconoscono e avere un tempo più facile per leggere il tuo codice.

Puoi usare tre citazioni per farlo.

Puoi usare le virgolette singole:

def myfunction(para1,para2):
  '''
  The stuff inside the function
  '''

O doppie virgolette:

def myfunction(para1,para2):
  """
  The stuff inside the function
  """