At what stage of package development do you write docstrings?

General Usage
1

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.

1 Like
2

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… :slight_smile:

3

I often start with the docstring. “Documentation-driven development” really helps with fully thinking through what the interface should be.

13 Likes
4

If Auto-generation of docstring · Issue #2787 · julia-vscode/julia-vscode · GitHub isimplemented it would be better for you.

5

Have a look at

which kind-of does this

3 Likes
6

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.

2 Likes
7

GitHub copilot is also very handy for that.

2 Likes
8

Where to hover? Tried various positions and have never seen one.

EDIT: it’ s the light bulb that didn’ t appear because a previous LSP crash due to fix stopline by xgdgsc · Pull Request #1228 · julia-vscode/LanguageServer.jl · GitHub. Thanks!

Is it possible to also add the argument explanation part?

9

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).

https://asciinema.org/a/cfj66hQZWGU5s7wSd2k74IFG7

1 Like
10

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.

1 Like
11

From the beginning. I usually review code for each commit (I make small commits) and add a docstring if it makes sense.

4 Likes
12

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.

1 Like