When I develop a package, I eventually write docstrings of functions so that the users can find the meanings and usages of the functions easily by help?>. However, I wait until the package gets matured, because I tend to refactor the code a lot: if I write docstrings too early, I need to change them whenever I refactor the code, which is annoying.
But creating the docstrings of all the functions at once after the package gets matured takes enormous time and effort. So I am wondering if I should change my package development practice. For example, if I spend more time on designing the function interfaces carefully from the start, then the function interfaces won’t change too often during package development. Then it might be OK to write the docstrings as I implement the functions, because even if the function bodies change, the docstrings don’t have to change as long as the function interfaces remain the same.
At what stage of package development do you write docstrings of functions? I’m curious about other developers’ practice.
An economist would say the optimal is when “marginal costs equate marginal benefits”…
No, kidding… I don’t think there is an universal alswer to when it is the best time to write the docstring… as you said it’s a trade off…
Something similar is also available from the language server. If you hover over a method signature without a docstring there is an option to add a docstring snippet. If you later update the method signature you can hover again and have the signature in the docstring be updated to match the source code.
Anywhere on the method signature (function foo() in the example below). I think “hover” in VS Code means that your cursor need to be there, it isn’t enough to just hover with the mouse. I tried in VS Code too and it works (see the yellow lightbuld that shows up).
I am also on the side of using the docs to clarify what I intend a function to do, what the input variables are, what the function should be called and by thinking about all this, writing the docs already. Sure that is a bit slower in writing code but usually has the large advantage that everything is directly documented.
Thank you all who replied! A bit surprised to learn that quite a few people write the docstrings from the start of defining functions. I will give it a try.