Wandering Thoughts archives

2017-01-25

I think docstrings in Python are for everything, not just public things

In my entry on my mixed feelings about docstrings, I mentioned that my most recent Python code was all comments and no docstrings, but also that it was a program instead of a module. So here's a question: should that matter for whether or not you use docstrings? The obvious related question is whether docstrings are for documenting everything in a module, or only the things people are supposed to use.

My best current answer is that if you're going to use docstrings at all, I think that they should be for everything. It's not that docstrings are how you make public documentation, things that you intend that people will use help() on and so on; instead, it's that docstrings are simply the Pythonic way to write function, method, class, and module documentation, whether those are intended for public use or not. Signaling which things are public versus private is best done through other mechanisms (such as a module level __all__ with public exports).

(At this point I will pause to admit that I took a quick look through the standard library and it doesn't seem to be entirely consistent on this. Most things that appear to be internal functions and that have documentation at all seem to use docstrings, but some of them have one or two line comments at the start where docstrings would normally go.)

Of course there are some things that you can't document with docstrings; constants and variables can't have docstrings attached, so you need to either use comments or cover them in the module level documentation.

(Here I'm talking about 'what this function does and how you call it' sort of documentation. Other sorts of commentary about the code and how things operate still go in comments because there isn't any other place where they belong, so you'll find those sort of comments scattered through the standard library as necessary.)

I also have no idea if this is a widespread view in the Python community. I have the impression that it is and the Django source code seems to use docstrings to document functions and so on, but it could be that people now see comments as the way to go outside of public stuff that should show up in help().

(I'll probably try to shift how I document things to docstrings for the next piece of Python code I write, assuming I remember this by then and don't give up in annoyance.)

DocstringsForEverything written at 01:32:47; Add Comment

2017-01-23

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 help() be pretty straightforward and non-magical; you basically combine dir() and looking at everything's __doc__. On the other hand, that __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 version of help() is rather more complicated.

(In theory this also decouples where docstrings live from help()'s 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.)

DocstringsMixedFeelings written at 01:12:52; Add Comment


Page tools: See As Normal.
Search:
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.