You will be rewarded sooner than you think when you use docstrings to document your classes and functions. Whether you ever intend to publish your work or not, docstrings will help you in several ways. First, let me show you the syntax:
- def Add(a, b):
-
"""Return the sum of two addable types.
-
This is a very simple example of docstring usage."""
-
return a + b
If you get into the habit of jotting down a short description of a function that you are writing (even before any of the body has taken shape), the first thing that you will be able to identify is whether you have factored the problem adaquately. If you can't describe the function in a line or two sentances, you may want to look at the problem again and see it you are not, in fact, trying to stuff too much into one function and should consider refactoring.
Secondly, docstrings are available in the Python shell via help() and dir(). So, if it's been a while since you have used one of your function you can import your library module and type
help(myLibModule.myFunc)
and your docstrings will be printed (this works for compiled modules, also).
Lastly, there are a few really cool automatic documentation tools that will read your module and make basic (but nice looking) documetation for you (but only if you use docstrings).