Python method docstring: to use or not to use Args: Returns:

Question

Default docstring from PyCharm automatically creates template with Args: and Returns: sections. However I have observed that this prompts people to say obvious things, frequently just stating the variable name without underscores (if name was chosen well).

My first external source was the source code of mypy, a project where GvR is one of the developers (therefore I expect it to be in line with best practices). Documentation there is plain english stating the purpose and further details, but everything about args and return is only in the (typed) method signature and var names.

However, PEP257 states: The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

Result is currently that I am trying to use best judgement on where we can make useful comments including Args: Returns: and where it is redundant, but this makes it look very diverse and unpredictable.

Background: I am trying to establish best practices for comments in a small python project (5 people).

Answer 1

Writing good documentation is an art unto itself. Repeating yourself (e.g., repeating the variable name without underscores) is valueless; e.g., ++i; // increment i. If you're just repeating variable names without underscores, then you're not adding to anyone's understanding of the code.

I think it's always important to document what exceptions your methods throw. Return values aren't always as obvious as the original programmer thinks they are, so that's usually useful to document as well. (Again, if your method is get_foo(), saying "returns a foo" doesn't add anything.)

One thing to point out about that mypy example, the authors are using type hints which replaces a lot of what would be included in a docstring:

def warn(self, msg: str, context: Context, file: Optional[str] = None,
             origin: Optional[Context] = None)

Just from this, I know exactly what this method expects. Without it:

def warn(self, msg, context, file = None, origin = None)

I know a lot less.

Answer 2

I can not give you a definite answer, since such documentation also is sort of work and as such should be done, if useful. Generally speaking, only useful functionality should be exposed to the user and the application should be easy to use and understand.

Arguments Even obvious things can be exported for fast lookup. This is usually helpful for long and tedious methods. Optional parameters can be easily integrated by default parameters.
Return values With python it can be a pain to look up return values by inspecting objects (without source code), so when the source code is not at hand this should be done.
Side effects This is a quite vague term, but at least thread-safety support should be annotated in mixed applications cases (or explicitely). Default however is not thread-safe.
Exceptions Enforcing programmer/user input should be definitely documented, since this will cause crashing behavior.

In a small project, and as such internal project, for given knowledge and (hopefully) code, it does not make too much sense to comment everything. Concentrate on data structures and use cases for functions.