Ho una funzione che accetta come argomenti un certo numero di classi di complessità media.
Durante la scrittura di docstring per quella funzione, mi imbatto in una serie di domande: dovrei descrivere (oltre a ciò che sta facendo la funzione) anche quelle classi, o posso supporre che il lettore scaverà la definizione della classe? O dovrei indicare dove sono definite le classi? Qual è la migliore pratica?
Qualsiasi IDE moderno dovrebbe consentire al lettore di passare alla definizione delle classi di riferimento con un solo clic del mouse. Non ha senso ripetere queste informazioni (la denormalizzazione dei dati a volte è una buona idea, ma non nella documentazione del software).
Pertanto, quando un metodo StringDistance prende String s come argomenti, non dovresti certamente descrivere cosa sia una stringa; quando LoanRiskCalculator usa Loan s, probabilmente non dovresti nemmeno descrivere Loan s. Questa informazione è posizionata meglio all'interno della classe Loan .
Il caso limite è quando le classi argomento sono classi helper dedicate che sono più o meno utili solo per l'uso con questo metodo o questa classe. Quindi può essere una buona idea descriverli insieme all'algoritmo che servono. Un metodo StringDistance che utilizza ReverseTrieLookupTable s per comunicare con altri metodi associati potrebbe estrarre la documentazione di thease helpers specilizzati nella propria docstring, o almeno nella docstring della classe.
Il termine specifico docstring che stai usando indica che stai usando Python. (O Cobra, ma quest'ultimo è molto meno probabile.)
Si noti che in Python, ciò che è rilevante è il protocollo , e non la classe dei parametri. (Questo è chiamato typing anatra , o in realtà solo OO.) Quindi, non dovresti documentare la classe affatto né per riferimento né per copia. La definizione di queste classi è completamente irrilevante.
Quale è rilevante, è ciò che protocollo la tua funzione si aspetta dai suoi parametri. Dovresti documentarlo. Inoltre, dovresti documentare quale protocollo la tua funzione garantisce per il suo valore di ritorno.
Leggi altre domande sui tag documentation documentation-generation