I wrote some nice things before about how I don't really use docstrings, but in thinking about it more I've realized that I was shading the truth. The real truth is that I don't really like using docstrings, and I've recently figured out why: docstrings don't stand out enough.

(I have to say here that I have nothing against documenting my code; I just want it to look right.)

Unless you use an editor and display environment that set docstrings off quite distinctly, docstrings look a lot like code (strange code, admittedly); there is nothing particular in their indentation or the start of the line that makes them stand out. Thus, it is sort of like reading Lisp for me: I have to pay attention to notice docstrings and make sure I am not merging docstrings and code together.

By contrast, comments have a quite visible marker in Python; when you are skimming code, it's very difficult to mistake a comment for code or miss a comment in the code. It is easy to page through a file looking only at comments (or only comments at a certain indentation level, or with a certain sort of formatting), or ignoring comments, much easier than doing the same thing with docstrings (without editor support).

(And I don't think it's an accident that common commenting methods in C do the same thing, despite it not being required. I think that people actively want comments to stand out quite distinctly, and this is probably one reason for the enduring popularity of 'start of line' comment markers in all sorts of programming languages.)

(This was crystalized by reading this entry and having the light suddenly go on about why my gut was curdling at the thought of lots of docstring usage to make my code look better, because I realized that I felt that it would actually make it look worse.)

In passing, I will note one advantage I see in docstrings being more merged into the code: it probably encourages a certain amount of terseness in function documentation. Speaking from personal experience, it's very easy to ramble on in comments, especially comments between functions, since they aren't all that distracting when I'm looking at the code.