docstrings in python programming

What is docstrings?

To quote PEP 257 from python's own documentation,

"

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

"

To ease this definition out, basically, a docstring is a piece of string or a small note which is generally provided in a class, function or a method definition for informing as well as documenting important information about the class, function or the method.

There are two basic types of docstrings, which are oneliner docstrings and multiline docstrings.

How to write docstrings?

docstrings are generally literal strings and therefore you can write them within """ triple double quotes""". But there are certain rules in case of unicode or backslashes.

If your docstring information is supposed to have backslash character then you have to use r"""raw triple double quotes""". If you have unicode docstring, then you have to use u""" unicoded triple double quote""".

What to write in docstrings?

There are a few guidelines for writing docstrings.

(1) docstrings should be written in triple quotes whether it is a one liner or not. Because it helps to maintain the structure and expand the doc later on if needed.

(2) docstrings for functions and methods should be in the form of instructions and not descriptions; i.e. instead of writing "it returns sum of two digits" one should write "return sum of two digits".

(3) docstring should be a proper summary of the object you are writing it for, instead of having any coding style writing like "func(a,b) -> a+b". It is supposed to give the reader or user a proper understanding of the main idea and the tasks performed by the object; which is not visible from the raw code.

(4) For a class or a module, you are expected to write long docstrings, containing small summaries of each of the class, function and methods involved. In case of a script, the docstring should be invoked when a wrong argument is passed or a help option is invoked. These are some advanced ideas in terms of docstrings.

How to read docstrings?

A docstring is a basic attribute of any python object. If there is a documentation provided in the object's source code, then object.__doc__ will provide the documentation. i.e. in order to access the docstring of a object, you have to write

print(object.__doc__) and then if it is present then it will get printed. If there is no docstring written then it will return nothing.

Conclusion:

In conclusion, I will advise you to start writing docstrings for your modules and functions from today. If you are writing a code which is to be reused then it is your duty to make it commented and well documented so that both users and developers who are going to either use it or work on further versions of it ; do not face steep problems in terms of readability and understanding of the code because of lack of maintenance. So start writing those docstrings from today.