Formats
Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in this blog post.
Note that the reST is recommended by the PEP 287
There follows the main used formats for docstrings.
- Epytext
Historically a javadoc like style was prevalent, so it was taken as a base for Epydoc (with the called Epytext format) to generate documentation.
Example:
"""
This is a javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
- reST
Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation. Note: it is used by default in JetBrains PyCharm (type triple quotes after defining a method and hit enter). It is also used by default as output format in Pyment.
Example:
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
Google has their own format that is often used. It also can be interpreted by Sphinx (ie. using Napoleon plugin).
Example:
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
Even more examples
- Numpydoc
Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.
"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
Converting/Generating
It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.
Note: The examples are taken from the Pyment documentation
Answer from daouzli on Stack OverflowThe method of documentation I learned in school is to list a function name, description, parameters, return type, and exceptions. It's serviceable, but a tad verbose and prone to redundancy. What do you recommend?
I am documenting the code for my new password manager. Here is the source on Github.
python - Is it consider bad practice to formally document implementation code? - Software Engineering Stack Exchange
Propper way to write DocStrings
Docstring vs Comments
What's the best guide/model to writing good docstrings for modules/classes/methods?
Formats
Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in this blog post.
Note that the reST is recommended by the PEP 287
There follows the main used formats for docstrings.
- Epytext
Historically a javadoc like style was prevalent, so it was taken as a base for Epydoc (with the called Epytext format) to generate documentation.
Example:
"""
This is a javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
- reST
Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation. Note: it is used by default in JetBrains PyCharm (type triple quotes after defining a method and hit enter). It is also used by default as output format in Pyment.
Example:
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
Google has their own format that is often used. It also can be interpreted by Sphinx (ie. using Napoleon plugin).
Example:
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
Even more examples
- Numpydoc
Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.
"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
Converting/Generating
It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.
Note: The examples are taken from the Pyment documentation
The Google style guide contains an excellent Python style guide. It includes conventions for readable docstring syntax that offers better guidance than PEP-257. For example:
def square_root(n):
"""Calculate the square root of a number.
Args:
n: the number to get the square root of.
Returns:
the square root of n.
Raises:
TypeError: if n is not a number.
ValueError: if n is negative.
"""
pass
I like to extend this to also include type information in the arguments, as described in this Sphinx documentation tutorial. For example:
def add_value(self, value):
"""Add a new value.
Args:
value (str): the value to add.
"""
pass
It is not necessarily bad practice to write doc strings for implementation code.
One thing to watch out for is that if the doc strings end up in official documentation, then other people might start to depend on internal details that you may want to be able to change at will. If that is a real concern for you, then you could also write the documentation in regular comments, rather than in a doc string.
Writing good documentation is hard and to most programmers (myself included) less fun than writing code. If you then add a bit of over-confidence on how readable your code is, then it becomes really easy to say "this internal function I just wrote is so clear, the code can stand on itself without additional documentation." The real proof of that statement usually comes several months later, when maintenance needs to be done and the code turns out to be less self-documenting than you thought.
It is very good on you if you can avoid that trap most of the time.
Public methods are used within a larger scope than non-public ones, and by a broader range of persons.
Non-public methods change more often than public ones (when the application is mature enough).
When it comes to comments, my first assertion means that it is much more important to document public methods. Those are the methods which would often be accessed by persons who don't necessarily have time (or interest) in exploring all the internals of the code: they just need to use the method, and they need to know how to use it. Inversely, those who will be interested by non-public methods are the persons who are often familiar with the class, and if not, they will have to become familiar with it, since they are modifying the class (otherwise, they wouldn't have to access non-public methods in the first place) or even the concerned method itself.
The second assertion means that it is costlier to keep the documentation of non-public methods up to date, especially when considering the ratio between public and non-public methods. If the method changes too often, it means that the documentation is read by fewer persons compared to the documentation of a public interface which remains the same for months or years.
To conclude, small-scope, non-public methods usually don't need as much documentation as public interfaces, and they are much more volatile. In other words, there is less money saved (in terms of future developers' time) by documenting a non-public method than a public one, and more money wasted constantly updating the documentation.
This explains PEP-8 guideline. One can imagine, obviously, some examples where it is absolutely crucial to document a non-public method, and examples where a public method is so self-explanatory, that it needs no comments. Those are the cases where that PEP-8 guideline should not be followed.