7

A python docstring must be given as a literal string; but sometimes it's useful to have similar docstrings for several functions (e.g., different constructors), or several access methods might accept the same list of arguments (and then rely on the same hidden method), so it would be nice to use the same description everywhere. For such cases I can construct a docstring by assigning to __doc__, which I do by means of a simple decorator. The system works very nicely (in python 2), and I'm pleased with how simple, clear and well-encapsulated it is.

The question: Is this a good idea? In particular, are there tools that would be confused by this set-up (e.g., anything that extracts docstrings from the source rather than from the bytecode). Is the solution still going to work in python 3? Are there other reasons or circumstances that would make this inadvisable?

alexis
  • 48,685
  • 16
  • 101
  • 161
  • "different constructors"? I assume you mean some kind of factory functions, because you can only have one `__init__`. – Karl Knechtel Mar 16 '12 at 22:37
  • I don't think "factory function" is right. I was referring to static members of a class, which create an instance of the same class. They'd all be polymorphic constructors in a language that supports that directly. But yes, factory functions might be another use case. – alexis Mar 17 '12 at 10:55
  • I would consider those a kind of factory, yeah. There isn't really any difference between static member functions and free functions (to use C++ terminology), besides namespacing. Although Python has separate "class method" and "static method" concepts. – Karl Knechtel Mar 17 '12 at 12:21

1 Answers1

4

It should not break any tools and it should work on Python 3.

It is ok If it doesn't hurt a source code readability i.e., you can still find out what the function does and how to use it.

The problem might be that it masks a poor design. If several methods use the same list of arguments the code should be refactored (create an object that works with the list) rather than patched by generating repetitive docstrings.

jfs
  • 399,953
  • 195
  • 994
  • 1,670
  • Thanks! Good to hear. I think the design is ok: The methods all call the same implementation method, and do things like return search results (from the object's content) in different formats. It's nice to have the different names at the interface for different operations, and anyway there's an existing API with standardized names. About the docstrings, it's easy enough to look at the implementation method when reading the source code. For interactive help, though, the interface methods should be documented. – alexis Mar 17 '12 at 11:06
  • Reopened the question because I hope to hear more feedback on this. No offense intended! – alexis Mar 17 '12 at 11:20