Ask HN: What docstring format do you prefer?
2 comments
I like the googlestyle with typehints a lot.
This will probably be a minority view, but I actually usually prefer to avoid docstrings. Basically: documentation is for users, comments are for developers, so docstrings are in the wrong place. For a long time I've felt that they're an ill-considered "Although practicality beats purity" convenience, and I'm growing more convinced of this over time. Of course documentation is important, but I would rather write it separately.
* They create the temptation to go function by function to describe the interface. This can be the wrong choice even in reference documentation. For example, information about how to construct an instance of a complex class is probably better put in the class documentation itself, rather than split across documentation for `__init__` and for various "factory" class methods. In general, documenting dunders directly feels a bit weird, because they are typically part of the "public interface" but still not meant to be called directly. I don't want to explain how to use `__add__`; I want to explain what expressions can be used involving `+`.
* Speaking of explanation: docstrings really aren't a place where the other essential forms of documentation (as described in the Diataxis model — https://diataxis.fr/) can fit. Therefore, thinking of documentation as "the thing you put in the docstrings" trains you to write incomplete documentation.
* They normalize using no-effect string literals, which trains you to abuse that instead of writing proper block comments.
* In my experience, quite a lot of code written by others ends up using docstrings to "document" things that aren't actually intended to be part of the public interface. (This is perhaps a consequence of the previous point.)
* They spread out the code and mess with my mental context window. Yes, you can set up things like https://github.com/yhat/vim-docstring to hide them. I still find it a significant speed bump. Might have to do with my coding style.
* Tooling like Sphinx reads external files anyway. Yes, with a docstring the tooling can in principle verify that the parameter descriptions correspond to the actual parameters, and/or automatically generate a description of the signature. Those things are also possible by just explaining in the external file which function is being documented. For that matter, in principle, external tooling could set `__doc__` attributes at runtime. I'm not aware of any that do, but it's a project I've thought of.
* By default, docstrings end up in the compiled bytecode (since the code could inspect them at runtime). Comments don't. So you effectively ship two copies of that text (that isn't related to program correctness) to end users, who will probably get that information from your online documentation anyway. (Or from a third copy in "generated" documentation provided with the distribution.)
* They create the temptation to go function by function to describe the interface. This can be the wrong choice even in reference documentation. For example, information about how to construct an instance of a complex class is probably better put in the class documentation itself, rather than split across documentation for `__init__` and for various "factory" class methods. In general, documenting dunders directly feels a bit weird, because they are typically part of the "public interface" but still not meant to be called directly. I don't want to explain how to use `__add__`; I want to explain what expressions can be used involving `+`.
* Speaking of explanation: docstrings really aren't a place where the other essential forms of documentation (as described in the Diataxis model — https://diataxis.fr/) can fit. Therefore, thinking of documentation as "the thing you put in the docstrings" trains you to write incomplete documentation.
* They normalize using no-effect string literals, which trains you to abuse that instead of writing proper block comments.
* In my experience, quite a lot of code written by others ends up using docstrings to "document" things that aren't actually intended to be part of the public interface. (This is perhaps a consequence of the previous point.)
* They spread out the code and mess with my mental context window. Yes, you can set up things like https://github.com/yhat/vim-docstring to hide them. I still find it a significant speed bump. Might have to do with my coding style.
* Tooling like Sphinx reads external files anyway. Yes, with a docstring the tooling can in principle verify that the parameter descriptions correspond to the actual parameters, and/or automatically generate a description of the signature. Those things are also possible by just explaining in the external file which function is being documented. For that matter, in principle, external tooling could set `__doc__` attributes at runtime. I'm not aware of any that do, but it's a project I've thought of.
* By default, docstrings end up in the compiled bytecode (since the code could inspect them at runtime). Comments don't. So you effectively ship two copies of that text (that isn't related to program correctness) to end users, who will probably get that information from your online documentation anyway. (Or from a third copy in "generated" documentation provided with the distribution.)
I personally like the brevity of typeless reStructuredText, but I see a lot of folks using Google.