All modules should normally have docstrings, and all functions and classes exported by a module should also have docstrings. Public methods (including the
__init__constructor) should also have docstrings.
I didn’t add many docstrings… I feel a bit bad about that now.
That said, I also know the argument that comments can quickly become outdated if the implementation changes and comments aren’t updated accordingly. Some people argue that we should rely on the implementation itself rather than adding comments that could become inconsistent and lead to confusion.
- String literals occurring immediately after a simple assignment at the top level of a module, class, or
__init__method are called “attribute docstrings”.- String literals occurring immediately after another docstring are called “additional docstrings”.
I was not aware of the “additional docstrings.”
As I browsed some web pages, I came to know Google Python
Style Guide. Because I already use black and also
haven’t met people who asked me to follow the Google’s style guide, so I
think I’m fine skipping this for now. Anyway, if you want to be very
strict, you should consider other options such as Rust or Haskell.
Python’s philosophy is to let developers do their things in their
ways.
The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each.
I rarely see this in public GitHub repositories.
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.
I think I should start with this, when appropriate, though I always try to make functions obvious and easy to understand, and comments or docstrings might complicate the code.
def add1(a: int, b: int) -> int:
"""Return the sum of two numbers"""
return a + b
print(f"{type(add1.__doc__)=}")
print(f"{add1.__doc__=}")
# type(add1.__doc__)=<class 'str'>
# add1.__doc__='Return the sum of two numbers'
def add2(num1: int = 0, num2: int = 0) -> int:
"""Return the sum of two numbers.
Keyword arguments:
num1 -- the first number (default 0)
num2 -- the second number (default 0)
"""
return a + b
print(f"{type(add2.__doc__)=}")
print(f"{add2.__doc__=}")
# type(add2.__doc__)=<class 'str'>
# add2.__doc__='Return the sum of two numbers.\n\n Keyword arguments:\n num1 -- the first number (default 0)\n num2 -- the second number (default 0)\n 'I think I should follow the Google’s Style Guide when working on a large project. (I don’t expect me to work on that kind of codebase).
TODO: