Lesson 5
Writing Reusable and Self-explanatory Programs
Chapter 7: Style conventions for functions
One-line docstrings
I have shown you one-line docstrings earlier.
def square(x):
""" Square the integer x."""
return x ** 2
These are for really obvious cases that don’t need further explanation.
They should really fit on one line.
Use triple quotes (rather than single quotes) even though the string fits on one line. It may turn longer in the future!
The closing quotes should be on the same line as the opening quotes. This looks better.
No blank lines before or after the docstring please.
The docstring itself is a phrase ending in a full stop/period. It should be written as a command (“Do this.”, “Return that.”), and not as a description; e.g. don’t write “Returns the square of x.”
The docstring should be a useful and meaningful description. Don’t write something like “square(x) -> float”. Write something like “Square the integer x and return it.” instead.