E 'una cattiva pratica avere docstring aggiornato dinamicamente?

Question

E 'una cattiva pratica avere docstring aggiornato dinamicamente?

#1 da (4 voti)
#2 da (1 voti)

2

Quando creo una docstring, a volte voglio fare riferimento a un valore, ad esempio:

def try_download(data, path):
    """Tries to download ATTEMPTS times, catching socket errors."""

Dove ATTEMPTS è solo una costante int definita all'inizio del file. Ma sarebbe meglio scriverlo in modo che stia generando una stringa indicando effettivamente qual è il valore, cioè.

def try_download(data, path):
    """Tries to download {} times, catching socket errors.""".format(ATTEMPTS)

Il vantaggio di questo, sarebbe che qualcun altro leggendo dinamicamente dalla funzione otterrebbe un messaggio più utile che indica il numero effettivo. Comunque qualcuno che legge lo script ha una frase leggermente meno leggibile. C'è anche un certo grado di pericolo che questo rende l'errore di docstring incline al fatto che errori potrebbero verificarsi, ma in realtà se è sostituito da un numero che non può essere stampato, la funzione effettiva avrà problemi maggiori di è docstring.

Quindi questo è preoccupante per niente, o è meglio stare al sicuro e non inserire variabili in docstring?

python documentation

posta SuperBiasedMan 04.08.2016 - 18:48

fonte

2 risposte

1

Secondo me un tale uso di docstring sarebbe inaspettato. Le docstring sono utilizzate per spiegare cosa fa un oggetto, spiegarne i parametri o proporre l'uso dell'oggetto.
Nel tuo caso stai dicendo qualcosa sull'esecuzione della tua funzione, non su come funziona, quindi non la creerei dinamicamente. Se questo è impostato all'inizio del file, potrebbe essere necessario come parametro e potresti spiegare che tale parametro controlla quante volte viene provato il download. Come hai notato potrebbe introdurre una nuova fonte di errori nella documentazione! È meglio mantenere la documentazione chiara e al punto.

risposta data 04.08.2016 - 19:42

fonte

Leggi altre domande sui tag python documentation

Pianificazione lavoro: algoritmo per trovare il numero massimo di lavori sovrapposti? Perché utilizzare X11 Windows in un toolkit GUI?

score 4 · Accepted Answer

L'approccio che stai descrivendo in realtà non produce una docstring. Non risulta nella proprietà __ doc __ della funzione impostata, il che significa che non è disponibile per la funzione aiuto e non sarebbe disponibile per (tipica) generatori di documentazione automatizzata. Ecco un semplice esempio che mostra questo in azione. Innanzitutto, una funzione con una docstring "tradizionale":

>>> def bar():
    "some value: 42"
    return 42

>>> bar.__doc__
'some value: 42'

>>> help(bar)
Help on function bar in module __main__:

bar()
    some value: 42

Tieni presente che la proprietà __ doc __ è impostata e aiuto mostrerà il contenuto di quella stringa. Ora proviamo con la "docstring" generata dinamicamente. Metto la docstring in virgolette da paura perché non è in realtà una docstring.

>>> def foo():
    "some value: {}".format(3)
    return 42

>>> foo.__doc__

>>> help(foo)
Help on function foo in module __main__:

foo()

Non c'è alcun valore per foo .__ doc __ e aiuto non mostra nulla a parte la dichiarazione della funzione, il che significa che il sistema non ha interpretato il valore come una docstring. Questo non è davvero sorprendente, dal momento che la prima espressione nel corpo della funzione non è una stringa, è una chiamata di funzione a una funzione membro di una stringa.

Quindi, per rispondere alle domande,

Is it poor practice to have dynamically updated docstrings?

Ci sono modi per aggiornare dinamicamente una docstring, vale a dire, impostando la proprietà __ doc __ della funzione, ma non è quello che sta facendo il tuo approccio. Che si tratti di buone o cattive pratiche probabilmente dipende dall'applicazione. Se stai generando dinamicamente alcune funzioni e desideri assegnare loro la documentazione, potrebbe andare bene. Nel modo in cui stai descrivendo, però, semplicemente non funziona.

The advantage to this, would be that someone else reading dynamically from the function would get a more helpful message indicating the actual number.

Dipende da cosa intendi per "leggere dinamicamente dalla funzione". potrebbe essere utile a qualcuno che legge la fonte, ma sicuramente non è utile a qualcuno che sta guardando l'output di aiuto , o che sta leggendo il valore di __ doc __ proprietà.