P
Pierre Asselin
Hi. Started using python a few months back, still settling on my style.
I write docstrings and I use "pydoc mymodule" to refresh my memory.
Problem: if I just docstring my classes/methods/functions the
output of pydoc more or less works as a reference manual, but if
I get sidetracked for even a few weeks I find that documentation
inadequate when I return to my code. I need to see some introductory
context first, so that the reference material makes sense.
Wery well, write a module docstring then. The problem now: the
many paragraphs of detailed description at the top of the module
get in the way. The pydoc output is good, but the code becomes
hard to read.
So I come up with this:
######################################################################
#! env python
"""One-liner docstring."""
# Many classes, methods, functions, attributes,
# with docstrings as needed. Docs tend to be
# short and the code speaks for itself.
# ...
# Much further down,
___doc___+= """
Detailed description goes here. Provide some context,
explain what the classes are for and what the most important
methods are, give simple examples, whatever. Say enough
to make the rest understandable."""
if __name__ == "__main__":
# test code follows
######################################################################
It seems to work, too. But is that a sound way to write python?
Am I relying on undocumented implementation details or am I safe?
I guess I am trying to control the order of exposition without
resorting to full-fledged Literate Programming.
I write docstrings and I use "pydoc mymodule" to refresh my memory.
Problem: if I just docstring my classes/methods/functions the
output of pydoc more or less works as a reference manual, but if
I get sidetracked for even a few weeks I find that documentation
inadequate when I return to my code. I need to see some introductory
context first, so that the reference material makes sense.
Wery well, write a module docstring then. The problem now: the
many paragraphs of detailed description at the top of the module
get in the way. The pydoc output is good, but the code becomes
hard to read.
So I come up with this:
######################################################################
#! env python
"""One-liner docstring."""
# Many classes, methods, functions, attributes,
# with docstrings as needed. Docs tend to be
# short and the code speaks for itself.
# ...
# Much further down,
___doc___+= """
Detailed description goes here. Provide some context,
explain what the classes are for and what the most important
methods are, give simple examples, whatever. Say enough
to make the rest understandable."""
if __name__ == "__main__":
# test code follows
######################################################################
It seems to work, too. But is that a sound way to write python?
Am I relying on undocumented implementation details or am I safe?
I guess I am trying to control the order of exposition without
resorting to full-fledged Literate Programming.