How to write meaningful docstrings?
Question:
What, in Your opinion is a meaningful docstring? What do You expect to be described there?
For example, consider this Python class’s __init__:
def __init__(self, name, value, displayName=None, matchingRule="strict"):
"""
name - field name
value - field value
displayName - nice display name, if empty will be set to field name
matchingRule - I have no idea what this does, set to strict by default
"""
Do you find this meaningful? Post Your good/bad examples for all to know (and a general answer so it can be accepted).
Answers:
What should go there:
Anything that you can’t tell from the method’s signature. In this case the only bit useful is: displayName – if empty will be set to field name.
I like to use the documentation to describe in as much detail as possible what the function does, especially the behavior at corner cases (a.k.a. edge cases). Ideally, a programmer using the function should never have to look at the source code – in practice, that means that whenever another programmer does have to look at source code to figure out some detail of how the function works, that detail probably should have been mentioned in the documentation. As Freddy said, anything that doesn’t add any detail to the method’s signature probably shouldn’t be in a documentation string.
I agree with "Anything that you can’t tell from the method’s signature". It might also mean to explain what a method/function returns.
You might also want to use Sphinx (and reStructuredText syntax) for documentation purposes inside your docstrings. That way you can include this in your documentation easily. For an example check out e.g. repoze.bfg which uses this extensively (example file, documentation example).
Another thing one can put in docstrings is also doctests. This might make sense esp. for module or class docstrings as you can also show that way how to use it and have this testable at the same time.
The most striking things I can think of to include in a docstring are the things that aren’t obvious. Usually this includes type information, or capability requirements – eg. “Requires a file-like object”. In some cases this will be evident from the signature, not so in other cases.
Another useful thing you can put in to your docstrings is a doctest.
From PEP 8:
Conventions for writing good documentation strings (a.k.a.
“docstrings”) are immortalized in PEP 257.
- Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you
should have a comment that describes what the method does. This
comment should appear after the “def” line.
- PEP 257 describes good docstring conventions. Note that most importantly, the “”” that ends a multiline docstring should be on a
line by itself, and preferably preceded by a blank line.
- For one liner docstrings, it’s okay to keep the closing “”” on the same line.
Check out numpy’s docstrings for good examples (e.g. http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).
The docstrings are split into several sections and look like this:
Compute the sum of the elements of a list.
Parameters
----------
foo: sequence of ints
The list of integers to sum up.
Returns
-------
res: int
sum of elements of foo
See also
--------
cumsum: compute cumulative sum of elemenents
Generally purpose of adding adding doc string in starting of function is to describe function, what it does, what it would return, and description about parameters. You can add implementation details if required. Even you can add details about author who wrote the code for future developer.
What, in Your opinion is a meaningful docstring? What do You expect to be described there?
For example, consider this Python class’s __init__:
def __init__(self, name, value, displayName=None, matchingRule="strict"):
"""
name - field name
value - field value
displayName - nice display name, if empty will be set to field name
matchingRule - I have no idea what this does, set to strict by default
"""
Do you find this meaningful? Post Your good/bad examples for all to know (and a general answer so it can be accepted).
What should go there:
Anything that you can’t tell from the method’s signature. In this case the only bit useful is: displayName – if empty will be set to field name.
I like to use the documentation to describe in as much detail as possible what the function does, especially the behavior at corner cases (a.k.a. edge cases). Ideally, a programmer using the function should never have to look at the source code – in practice, that means that whenever another programmer does have to look at source code to figure out some detail of how the function works, that detail probably should have been mentioned in the documentation. As Freddy said, anything that doesn’t add any detail to the method’s signature probably shouldn’t be in a documentation string.
I agree with "Anything that you can’t tell from the method’s signature". It might also mean to explain what a method/function returns.
You might also want to use Sphinx (and reStructuredText syntax) for documentation purposes inside your docstrings. That way you can include this in your documentation easily. For an example check out e.g. repoze.bfg which uses this extensively (example file, documentation example).
Another thing one can put in docstrings is also doctests. This might make sense esp. for module or class docstrings as you can also show that way how to use it and have this testable at the same time.
The most striking things I can think of to include in a docstring are the things that aren’t obvious. Usually this includes type information, or capability requirements – eg. “Requires a file-like object”. In some cases this will be evident from the signature, not so in other cases.
Another useful thing you can put in to your docstrings is a doctest.
From PEP 8:
Conventions for writing good documentation strings (a.k.a.
“docstrings”) are immortalized in PEP 257.
- Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you
should have a comment that describes what the method does. This
comment should appear after the “def” line.- PEP 257 describes good docstring conventions. Note that most importantly, the “”” that ends a multiline docstring should be on a
line by itself, and preferably preceded by a blank line.- For one liner docstrings, it’s okay to keep the closing “”” on the same line.
Check out numpy’s docstrings for good examples (e.g. http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).
The docstrings are split into several sections and look like this:
Compute the sum of the elements of a list.
Parameters
----------
foo: sequence of ints
The list of integers to sum up.
Returns
-------
res: int
sum of elements of foo
See also
--------
cumsum: compute cumulative sum of elemenents
Generally purpose of adding adding doc string in starting of function is to describe function, what it does, what it would return, and description about parameters. You can add implementation details if required. Even you can add details about author who wrote the code for future developer.