È considerata una cattiva pratica documentare formalmente il codice di implementazione?

Non è necessariamente una cattiva pratica scrivere stringhe di documenti per il codice di implementazione.
Una cosa a cui prestare attenzione è che se le stringhe doc finiscono nella documentazione ufficiale, allora altre persone potrebbero iniziare a dipendere da dettagli interni che potreste voler modificare a piacimento. Se questa è una vera preoccupazione per te, allora potresti anche scrivere la documentazione in commenti regolari, piuttosto che in una stringa doc.

Scrivere una buona documentazione è difficile e per la maggior parte dei programmatori (me compreso) meno divertente della scrittura del codice. Se poi aggiungi un po 'di confidenza su quanto è leggibile il tuo codice, diventa davvero facile dire "questa funzione interna che ho appena scritto è così chiara, il codice può stare su se stesso senza ulteriore documentazione". La vera prova di questa affermazione di solito arriva diversi mesi dopo, quando è necessario eseguire la manutenzione e il codice risulta meno autodocumentante di quanto si pensasse.
È molto buono con te se puoi evitare quella trappola la maggior parte del tempo.

1. I metodi pubblici vengono utilizzati in un ambito più ampio rispetto a quelli non pubblici e da un più ampio numero di persone.

2. I metodi non pubblici cambiano più spesso di quelli pubblici (quando l'applicazione è abbastanza matura).

Quando si tratta di commenti, la mia prima affermazione significa che è molto più importante documentare i metodi pubblici . Questi sono i metodi a cui spesso si accede da persone che non hanno necessariamente tempo (o interesse) nell'esplorare tutti gli interni del codice : hanno solo bisogno di usare il metodo, e hanno bisogno di sapere come usarlo Inversamente, coloro che saranno interessati da metodi non pubblici sono le persone che hanno spesso familiarità con la classe, e in caso contrario, dovranno familiarizzarsi con essa, poiché stanno modificando la classe (altrimenti, non avrebbero per accedere ai metodi non pubblici in primo luogo) o anche al metodo in questione.

La seconda asserzione significa che è più costoso mantenere aggiornata la documentazione dei metodi non pubblici , soprattutto se si considera il rapporto tra metodi pubblici e non pubblici. Se il metodo cambia troppo spesso , significa che la documentazione viene letta da un minor numero di persone rispetto alla documentazione di un'interfaccia pubblica che rimane invariata per mesi o anni.

Per concludere, i metodi non pubblici di portata limitata, di solito non hanno bisogno di tanta documentazione quanto le interfacce pubbliche e sono molto più volatili. In altre parole, si risparmiano meno soldi (in termini di tempo futuro degli sviluppatori) documentando un metodo non pubblico rispetto a uno pubblico e più denaro sprecato aggiornando costantemente la documentazione.

Questo spiega la linea guida PEP-8. Si possono immaginare, ovviamente, alcuni esempi in cui è assolutamente cruciale documentare un metodo non pubblico, ed esempi in cui un metodo pubblico è così auto-esplicativo, che non ha bisogno di commenti. Questi sono i casi in cui tale linea guida PEP-8 non dovrebbe essere seguita.

La documentazione del codice di implementazione non è solo una cattiva pratica, è raccomandata e persino necessaria se la base di codice è grande. Tuttavia, esiste un altro stile di documentazione richiesto e ha un altro scopo oltre alla documentazione del codice pubblico.

Il codice pubblico deve essere documentato in modo tale che gli utenti sappiano cosa fare. Ogni pezzo di documentazione dovrebbe essere il più possibile autoesplicativo, in modo tale che l'utente non debba leggere pezzi di documentazione per un'ora prima di poter utilizzare una funzione. Deve essere chiaro, completo, facile da capire, anche se questo potrebbe renderlo più dettagliato.

D'altro canto, la documentazione interna deve essere letta da persone che sono interessate a mantenere il codice di base. Pertanto, può assumere un maggiore livello di familiarità con il progetto e dovrebbe essere più conciso.

Personalmente, mi sento come se le docstring fossero troppo prolisse per il codice di implementazione. Il mio obiettivo è un codice di auto-documentazione (ad esempio, nomi e variabili espressivi sufficienti) e, se necessario, aggiungo alcuni commenti.

Naturalmente, le docstring per il codice privato non danneggiano di per sé, ma tieni presente che sono più lunghe e richiedono molta più manutenzione di un semplice commento, senza aggiungere molto valore.

Lo stesso paragrafo che hai citato spiega che dovresti usare i commenti per documentare moduli, funzioni, classi e metodi non pubblici. Le docstring sono la documentazione per gli utenti del tuo codice, i commenti sono la documentazione per i mantainer del tuo codice.