A docstring is a literal string description or definition of a module, function, class, or method in the Python code. It becomes the __doc__ attribute of that object.
A docstring corresponds to something like the following:
def function(a, b):
"""function(a, b) -> list"""
Or even something more comprehensive like this:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
On the other hand, unlike the usual comments, a docstring facilitate the task of consulting the description of a module, function, class, or method from the Python interpreter, without requiring access to the source code to understand its operation, facilitating its usage.
All of this is a technical matter, but the real deal about it is to make the code readable and understandable with the intention of attract as many contributors as possible.
If the code of a project is not well documented, commented or described, there is no one who would want to use it or much less contribute to it. So if you're taking the time to code something transcendental or productive, then try to incorporate docstrings in the process, as this will allow a better diffusion of the project, or at least later will allow you to better understand what you did in the past. It is a good practice for you and for everybody in the programing world.
Source: http://www.python.org/dev/peps/pep-0257/
No comments:
Post a Comment