I find that in my code, many methods in a class or a set of related classes have quite similar 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.

There might be 5 or more different methods in my class that all use some of these arguments. Some use additional arguments, others may use only a subset. They all do somewhat different things. Internally they use some (pseudo-)private methods to avoid code repetition. Then those are subclassed by perhaps a dozen different classes, that all contain implementations of those three. To take care of the subclasses, I'm using a metaclass that will transfer the docstring of the (abstract) superclass, so the docstring gets copied automatically.

My code has only minimal repetition, but my docstrings contain considerably duplication. What is an effective strategy to avoid repetition in docstrings? I could link from the documentation of method_b to the documentation of method_a, but then the documentation for method_b gets scattered from a user point of view. Or I could repeat the relevant part of the documentation for method_a in the docstring for method_b, but then I end up with repetitions that are hard to maintain.

I'm using Python, so my language is sufficiently dynamic to generate docstrings runtime, such as I do with metaclasses. But I'm interested in generic, language-agnostic strategies.


It sounds like you're putting too much background information in your docstrings, no? Preconditions and postconditions should never be long enough to warrant a concern like this.

You could consider putting background information and "general rules" for usage of your class in a single docstring for the class itself.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.