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.

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, because it shows up in editors when hovering. We’re not forced, but as a lead, I encourage it.

yes

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

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.

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