My still-mixed feelings about Python's docstrings
I've written before
about why I'm not really fond of docstrings in Python. I continue
to feel that way, but at the same time I have to acknowledge that
the Python world has made its decision; although
help() et al
have some heroic hacks to deal with documentation comments, the only fully supported in-Python way to document
your module for other people is with docstrings.
This doesn't mean that docstrings are the best way to document your
modules. Python's own module documentation, for example for the
os module, is much
more extensive than what '
help()' on the module will give you.
The in-Python version is basically a moderate summary of the full
documentation. But writing this sort of documentation is a lot of
work, and if you're only going to write documentation for a public
module in one place and once, it's clear that it has to be docstrings.
I tend to write docstring based documentation only erratically for non-public code. Documentation in comments simply looks better and 'more right' to me (and I find it less distracting when it's placed before a declaration, instead of between a declaration and the code as a docstring needs to be). I assume that anyone who needs to work with the code is going to have to read it, at which point they're going to see the comments. However this is partly because we don't have a stand-alone collection of Python modules that are reused across disparate programs, which means that I'm basically never in a situation where I just want to know what a module does so I can use it in a new program.
I definitely have mixed feelings about how Python has chosen to
explicitly expose docstrings as attributes on functions, classes,
and so on. On the one hand, it makes the simple version of
be pretty straightforward and non-magical; you basically combine
dir() and looking at everything's
__doc__. On the other hand,
__doc__ is exposed to Python code has tempted me into
abusing it for passing around other function-related information
that I wanted my code to have access to. And of course the real
help() is rather more complicated.
(In theory this also decouples where docstrings live from
implementation. For example, Python 3.x could decide to turn
properly formatted comments that are right before declarations into
docstrings if the declaration didn't itself already have a docstring.)
My aesthetic feelings about how docstrings look are probably significantly cultural, in that most of the programming languages I've used and been exposed to used explicit comments and not docstrings and so I'm not used to them. I don't know if docstrings read more naturally to people who 'grew up' in Python and similar languages, but I suspect that they may well do so. Perhaps I should make an effort to write more docstrings in future Python code, instead of reflexively documenting everything in comments.
(Not that I write much Python code these days. But my most recent Python code was once again all comments and no docstrings, although it's a program and not a module.)