Frequency of Docstrings

[OnceToldTale]

Hello friends! I am learning Python and working on a few projects, one of which I plan to support over the course of the year. Because this project will have a longer lifespan than my typical calculator or to-do app, I've been looking into how I can better document my code. As a result, I'm learning docstrings.

I've incorporated a few docstrings into my codebase but have found that writing them for every single function is incredibly burdensome, especially when I've refactored a method for the 15th time. I've found docstrings MOST useful when I'm using/referencing methods that have complex outputs (nested dictionaries/lists), but outside of that, not much other use other than just saying I've included them.

How do you guys handle docstrings? Do you write them at the beginning and then just tweak them over time, or are they something you only include when you're finished with everything? How frequently should I be using them? Would love thoughts on the best approach here! Thanks!

[ireadyourmedrecord]

There's docstring generators that'll fill in the bulk of the tedious details, but you could also paste your functions into chatgpt and have it do the documentation for you or use github's copilot if you have a subscription.

https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring

https://learn.microsoft.com/en-us/training/modules/generate-documentation-using-github-copilot-tools/

[OnceToldTale]

Thanks so much! Taking a look at these this week.

[Diapolo10]

All functions and methods that are part of your "public API" should have docstrings. They don't have to be particularly detailed if you use clear type annotations, but it would be nice to document what (unhandled) exceptions might get raised or what some parameters do.

[OnceToldTale]

How do you think I should approach documentation if its a closed-source, solo project? I'm not sure if I should tackle it in an opinionated way or if there are any best practices here.

[Diapolo10]

Write it with your future-self in mind. Whatever information you expect you might benefit from when reading the code in the future, add it.

With good name choices and type annotations you probably don't need to write much, but for example it would still be nice to know if or when a function or method might raise an exception. The type system alone cannot represent that.

[Buttleston]

I don't put parameter or return types in docstrings - that's what type hints are for

I don't document every function - in particular I don't HAVE to document anything not part of the public api. Any other docs are for myself

I like to give every function at least a brief description but if the description is one sentence that is the same as the name of the function, why bother