Docstrings vs Commenti

Question

Sono un po 'confuso sulla differenza tra docstring e commenti in python.

Nella mia classe il mio insegnante ha introdotto qualcosa di noto come "ricetta del design", una serie di passaggi che presumibilmente ci aiuteranno a pianificare e organizzare meglio la nostra codifica in Python. Da quello che ho capito, il sotto è un esempio dei passi che seguiamo - questo in modo da chiamare ricetta di progettazione (la roba delle quotazioni):

def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark): 

    ''' (float, float, float, float, float) -> float 

    Takes your marks on a0_mark, a1_mark, a2_mark, ex_mark and midterm_mark, 
    calculates their respective weight contributions and sums these 
    contributions to deliver your overall term mark out of a maximum of 55 (This 
    is because the exam mark is not taken account of in this function) 

    >>>term_work_mark(5, 5, 5, 5, 5) 
    11.8 
    >>>term_work_mark(0, 0, 0, 0, 0) 
    0.0 
    ''' 

    a0_component = contribution(a0_mark, a0_max_mark, a0_weight) 
    a1_component = contribution(a1_mark, a1_max_mark, a1_weight) 
    a2_component = contribution(a2_mark, a2_max_mark, a2_weight) 
    ex_component = contribution(ex_mark, exercises_max_mark,exercises_weight) 
    mid_component = contribution(midterm_mark, midterm_max_mark, midterm_weight) 
    return (a0_component + a1_component + a2_component + ex_component + 
      mid_component) 

Per quanto ho capito questo è fondamentalmente un docstring, e nel nostro la versione di una docstring deve includere tre cose: una descrizione, esempi di cosa dovrebbe fare la tua funzione se la inserisci nella shell python e un 'tipo contract', una sezione che mostra quali tipi inserisci e quali tipi funzionano sarà di ritorno.

Ora questo è tutto fatto, ma i nostri compiti ci impongono di avere anche commenti che spiegano la natura delle nostre funzioni, utilizzando il simbolo "#" del token.

Quindi, la mia domanda è, non ho già spiegato cosa farà la mia funzione nella sezione descrizione della docstring? Qual è il punto di aggiungere commenti se essenzialmente dirò al lettore la stessa identica cosa?

Inoltre, a proposito, sto avendo un momento assolutamente orrendo cercando di ottenere questo codice per uscire correttamente una volta nel post effettivo. Mi dispiace per quello Non suppongo che qualcuno potrebbe indicarmi la giusta direzione per formattare correttamente il codice in un post?

Answer 1

Prima di tutto, per la formattazione dei post è possibile utilizzare le opzioni della guida sopra l'area di testo che si digita il post.

E sui commenti e sulle stringhe doc, la stringa doc è lì per spiegare l'uso generale e le informazioni di base dei metodi. D'altra parte i commenti hanno lo scopo di fornire informazioni specifiche su blocchi o linee, #TODO è usato per ricordarti cosa vuoi fare in futuro, definizione di variabili e così via. A proposito, in IDLE la stringa doc viene mostrata come suggerimento quando passi il mouse sopra il nome del metodo.

Answer 2

Citando a questa pagina http://www.pythonforbeginners.com/basics/python-docstrings/

stringhe di documentazione Python (o docstrings) forniscono un modo conveniente di associare documentazione con moduli Python, funzioni, classi, e metodi.

La sincronizzazione di un oggetto viene definita includendo una costante di stringa come prima istruzione della riga nella definizione dell'oggetto.

E 'specificato nel codice sorgente che viene utilizzato, come un commento, per documentare un segmento specifico di codice.

A differenza dei commenti di codice sorgente convenzionali, la docstring deve descrivere cosa fa la funzione, non come.

Tutte le funzioni devono avere un docstring

In questo modo il programma di ispezionare questi commenti in fase di esecuzione, per esempio come sistema di aiuto interattivo, o come metadati.

docstrings sono accessibili dal __ doc __ attributo oggetti.

1. docstrings si può accedere attraverso un programma (__doc__) dove, come commenti in linea non è possibile accedere.
2. I sistemi di guida interattiva come in bpython e IPython possono utilizzare le docstring per visualizzare la documentazione durante lo sviluppo. In modo che non devi visitare il programma ogni volta.

Answer 3

Sembra che il tuo insegnante è un fan di come progettare programmi;)

mi piacerebbe affrontare questo come la scrittura per due diversi tipi di pubblico che non sempre si sovrappongono.

Prima ci sono le docstring; queste sono per le persone che useranno il tuo codice senza aver bisogno o voler sapere come funziona. Le docstrings possono essere trasformate in una vera documentazione. Considera la documentazione ufficiale di Python - Cosa è disponibile in ogni libreria e come usarlo, nessun dettaglio di implementazione (A meno che non si riferiscano direttamente all'utilizzo)

In secondo luogo ci sono commenti in codice; questi sono per spiegare cosa sta succedendo alle persone (generalmente voi!) che vogliono estendere il codice. Questi non verranno normalmente convertiti in documentazione poiché riguardano il codice stesso piuttosto che l'utilizzo. Ora ci sono tante opinioni su ciò che rende buoni i commenti (o meno) perché ci sono i programmatori. Le mie regole pratiche per aggiungere commenti sono:

• Parti del codice necessariamente complesse. (Ottimizzazione viene in mente)
• Soluzioni alternative per il codice non si ha il controllo su, che potrebbero altrimenti apparire illogica
• Devo ammettere di TODOs e, anche se cerco di mantenere che al minimo
• Dove Ho fatto una scelta di un algoritmo più semplice in cui l'opzione migliore (ma più complessa) può andare se le prestazioni in quella sezione diventano più critiche

Dato che stai codificando in un ambiente accademico, e suona come il tuo docente sta andando a verbosa, direi che ci sto semplicemente tirando. Usa i commenti del codice per spiegare come stai facendo ciò che dici che stai facendo nella ricetta del design.

Answer 4

Credo che valga la pena menzionare cosa dice PEP8, voglio dire, il concetto puro.

docstrings

convenzioni per la scrittura stringhe di documentazione (pseudonimo "docstring") sono immortalati in PEP 257.

docstrings scrittura per tutti i pubblici moduli, funzioni, classi e metodi. Le didascalie non sono necessarie per i metodi non pubblici, ma dovresti avere un commento che descriva cosa fa il metodo. Questo commento dovrebbe apparire dopo la def.

PEP 257 descrive buone convenzioni di documentazione. Si noti che la cosa più importante, il "" "che finisce un docstring multilinea dovrebbe essere su una riga da solo, ad es .:

"""Return a foobang 

Optional plotz says to frobnicate the bizbaz first. 
""" 

Per uno docstrings di copertina, si prega di tenere la chiusura ''" sulla stessa linea.

Commenti

Block commenta

applicata in via generale per alcune (o tutte) il codice che li segue, e sono rientrate allo stesso livello di quella del codice. Ogni riga di un commento di blocco inizia con un # e un singolo spazio (a meno che non sia un testo rientrato all'interno del commento).

I paragrafi all'interno di un commento di blocco sono separati da una riga contenente un singolo #.

Inline Commenti

Utilizzare i commenti in linea con parsimonia.

Un commento in linea è un commento sulla stessa riga di un'istruzione. I commenti in linea devono essere separati da almeno due spazi dall'istruzione. Dovrebbero iniziare con un # e un singolo spazio.

I commenti in linea non sono necessari e di fatto distolgono se affermano l'ovvio.

non farlo:

x = x + 1 # Incrementa x

Ma a volte, questo è utile:

x = x + 1 # Compensare per confine

Riferimento

• https://www.python.org/dev/peps/pep-0008/#documentation-strings
• https://www.python.org/dev/peps/pep-0008/#inline-comments
• https://www.python.org/dev/peps/pep-0008/#block-comments
• https://www.python.org/dev/peps/pep-0257/