Yeah, they’re definitely still the standard. They’re not really replaced by comments, comments are more for explaining why bits of code are the way they are. Docstrings are kind of like comments for functions/classes/etc that Python knows how to handle specially. The interpreter will parse the docstrings and make help text out of them available to the help builtin function

At my work we use linters that refuse code with missing or bad docstrings.

Yes they are sometimes used, as is doctest, but Python’s built in help system isn’t as good as it could be, so the docstrings aren’t that useful. Most annoyingly, for built in library classes, help(whatever) spews machine generated prototypes at you before you get any actual documentation.

I generally like to write some kind of explanatory text along with any nontrivial function that I write, but I’m not very consistent about doing this as a doctring vs as a code comment. I do use type annotations heavily nowadays.

Yup, use docstrings and be descriptive. Learn by reading docstrings in other codebases. (Django’s codebase is always an excellent example of how to do Python, including how to do docstrings.) a) Anyone who sees your code will thank you and b) if you can’t explain it in human language, you probably don’t understand it well enough to implement it well.

yes

Yes, use them. One big advantage is if you hover something in an IDE it will show you the docstring.

If you’re writing Python you should be using Pylint (or Ruff) and it has a lint to ensure you write them.

The exception I usually make is for class member variables because it’s super weird that the docstring comes after the variable. I think that’s very confusing for people reading the code so I normally just use comments instead.

Sounds like they’re still very relevant and very important. Python isn’t a language I’ve used a lot but I’m still surprised I’ve never heard about docstrings till this tutorial. Thanks for the info.

Yes, because it shows up in editors when hovering. We’re not forced, but as a lead, I encourage it.

Docstrings are important and their role is different than comments. They give an overview how the function works, explain parameters and sometimes give examples how to use them. You can generate documentation using sphinx from Docstrings, and as others said IDEs use docstrings to show you information about function you’re using.

Comments are just text that gets ignored by interpreter. You can add explanation to code if it’s not self explanatory, but they’re not useful outside of the immediate area being commented on.

Other languages also have documentation options that is separate from comments, e.g. JavaDoc. The syntax is usually similar to coment, but slightly different to differentiate it from comments (extra * in multiline comment).

i use interrogate

Which has a fun bug. Uses ast to compile every module. If a module contains a compile error, get a traceback showing only the one line that contains the issue, but not the module path nor the line #

The only way to find the issue is to just test your code base and ignore interrogate until code base is more mature.

interrogate author and maintainers: UX … what’s that?

The most obvious bug in the history of bugs … setuptools maintainers, oh that’s a feature request

If you want to see doctrings in action, take a look at Salt (saltproject.io). They’re used to build all the module documentation (docs.saltproject.io/en/latest/py-modindex.html) using sphinx and they won’t accept new modules without them.