Python Comments vs Docstrings

When I have gone through the Python tutorial, came across an interesting topic in Python. It is a Python docstring. A docstring is short for documentation string.

Python comments

Comments are descriptions which help the programmers to understand the intend and the behaviour of the function. It is a best practice to write comments while writing code.

In Python, we use # symbol to write single line comments.

# Print ‘Hello World’
print("Hello World")

For multiline comments we use triple quotation( single quotation or double quotation ) marks.

'''
This is the
example for the
multiline comments
'''

Comments are completely ignored by the Python interpreter but we can access docstrings using the __doc__ attribute.

Python Docstrings

Docstrings are similar to comments but docstrings are more logical and useful version of commenting. It is description about the functions, classes and modules. We can write docstrings to all our own codes. Python also have built-in docstrings for Python functions, classes and modules.

We can use triple """ quotations to create docstrings.

def add(a, b):
'''Takes two arguments, returns the addition of two arguments'''
return a + b
print(add.__doc__)Output:
Takes two arguments, returns the addition of the values

Built-in Docstrings

We will try for built-in print function,

print(print.__doc__)

Output

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

This is the documentation of the print function.

Docstrings for Python class

We will print the docstrings for this class

print(Person.__doc__)

Output

Attributes
----------
name : str
first name of the person
age : int
age of the person

Methods
-------
info:
Prints the person's name and age.

We can also use the help() function to read the docstrings.

help(Person)

Output

Help on class Person in module __main__:

class Person(builtins.object)
| Person(name, age)
|
| Attributes
| ----------
| name : str
| first name of the person
| age : int
| age of the person
|
| Methods
| -------
| info:
| Prints the person's name and age.
|
| Methods defined here:
|
| __init__(self, name, age)
| Constructs all the necessary attributes for the person object.
|
| info(self, additional='')
| Prints the person's name and age.
|
| ----------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)

We can use the docstrings for Python scripts and packages also. We can write docstrings in many formats. To learn more about formats, visit Popular Docstring Formats

I hope this blog is useful to you. I have shared the information that I learned from the tutorial. If you have came across any other interesting things about docstrings please add in the comments.

Ruby On Rails Developer, Learning Python and Libraries