Trovo che nel mio codice, molti metodi in una classe o un insieme di classi correlate abbiano argomenti abbastanza simili:
Arguments:
dt_start (datetime): Starting date.
Needs to meet complex requirements x and y and z. If not p then q or
the unicorns will be bitten by the python. An antidote may be hard to
find. Bla bla bla, long story.
dt_end (datetime): Ending date.
Last file may exceed beyond this point. More warnings. Etc. etc.
**extra: extra keyword arguments. Will be passed on to specific
implementation for this class. Blah blah blah.
Ci potrebbero essere 5 o più metodi diversi nella mia classe che usano tutti alcuni di questi argomenti. Alcuni usano argomenti aggiuntivi, altri possono usare solo un sottoinsieme. Fanno tutti cose un po 'diverse. Internamente usano alcuni (pseudo) metodi privati per evitare la ripetizione del codice. Quindi quelli sono sottoclassi di forse una dozzina di classi diverse, che contengono tutte le implementazioni di questi tre. Per occuparmi delle sottoclassi, sto usando una metaclasse che trasferirà la docstring della superclasse (astratta), quindi la docstring viene copiata automaticamente.
Il mio codice ha solo una ripetizione minima, ma le mie docstrings contengono una notevole duplicazione. Qual è una strategia efficace per evitare la ripetizione nelle docstring? Potrei collegare dalla documentazione di method_b alla documentazione di method_a , ma poi la documentazione per method_b viene dispersa dal punto di vista dell'utente. Oppure potrei ripetere la parte rilevante della documentazione per method_a nella docstring per method_b , ma poi finisco con ripetizioni difficili da mantenere.
Sto usando Python, quindi il mio linguaggio è sufficientemente dinamico per generare runtime di docstrings, come faccio con le metaclassi. Ma mi interessano le strategie generiche e indipendenti dalla lingua.