When documenting Python, when should I use docstrings and when should I use comments?

Question

Python programming language provides two mechanisms for documenting a function, a module or a class:

1. Comments and
2. Documentation strings (or Docstring).

Both can be accessed by reading the source code, but the latter is also available by calling the help() function.

Since documentation strings are more versatile, does it make sense to use comments at all, especially the comments that explain the purpose of the function/class/module?

Answer 1

PEP 8 -- Style Guide for Python Code categories comments and document strings (a.k.a. docstrings) under comments sections.

Comments

1. Block Comments
2. Inline Comments
3. Documentation Strings

Block comments generally apply to some (or all) code that follows them and are indented to the same level as that code.

Inline comments are unnecessary and in fact distracting if they state the obvious.

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition.

---

Now to answer your question

Docstrings are for people who are going to be using your code without needing or wanting to know how it works. Docstrings can be turned into actual documentation. Consider the official Python documentation - What's available in each library and how to use it, no implementation details (Unless they directly relate to use).

In-code comments are to explain what is going on to people those who want to extend the code. These will not normally be turned into the documentation as they are really about the code itself rather than usage. Now there are about as many opinions on what makes for good comments (or lack thereof) as there are programmers. My personal (credits) rules of thumb for adding comments are to explain:

• Parts of the code that are necessarily complex. (Optimisation comes to mind).
• Workarounds for the code you don't have control over, that may otherwise appear illogical.
• I'll admit to TODOs as well, though I try to keep that to a minimum.
• Where I've made a choice of a simpler algorithm where a better performing (but more complex) option can go if performance in that section later becomes critical.

Answer 2

Code comments and docstrings have different purposes and audiences:

• Developers write docstrings to describe the function's behaviour. Other developers, who use this function, read docstrings to find about the meaning of parameters, the pre- and post-conditions, possible exceptions etc.

  If you're writing an API, you may want to publish docstrings as a part of documentation, but have your code and code comments private.

• Developers write comments to describe the code's inner logic, when this logic isn't clear from just reading the code. The audience is themselves and other developers, who will modify this function in the future.