David Abrahams wrote:
Is it just me, or are docstrings less-convenient than comments?
How do you mean?
I don't know, it's hard to put into words, but I'll try:
1. 5 more characters just to get started. Probably a shift key too, if I'm going to be stylistically conformant with other work I've seen. ("""...""").
If the docstring is more than a few lines long, the quotes become average out to less than "#" in comments. Easier to edit docstrings; no per-line prefix.
2. The docstring separates the function signature from its body, which tends to obscure the code a bit. I prefer prefix documentation.
I suppose that's valid. It comes down to what you're used to. You could put triple-quoted multi-line strings before the "def", but they wouldn't be accessible or particularly useful. Triple-quotes can be used as multi-line comments, at least for temporary ones.
3. Weird indentation when the docstring spans multiple lines
def foo(bar, baz): """Start of doc rest of doc and some more doc""" function_body()
The convention is to indent all lines of the docstring equally, and to put the closing triple-quotes on a line by themselves. I prefer to put the opening triple-quotes on a line by themselves too. It would end up looking like this:: def foo(bar, baz): """ Start of doc rest of doc and some more doc """ function_body()
Documentation is really hard to start with, and every additional barrier to entry is unacceptable to me. Every time I write a doc string, I think of all 3 of the above things, which causes a little "cognitive dissonance", and makes it less likely that I'll write another.
You can still write prefix comments. HappyDoc extracts them, but they're not accessible from the running program or from the interactive interpreter. Better in the long run (for you and others who use your code) to embrace the features Python gives you. Confusing otherwise. Nobody's forcing you though. -- David Goodger goodger@users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net