Day #29 - Docstrings in Python

Day #29 - Docstrings in Python

Introduction

Welcome to my 29th blog post. Previously we have seen that whenever we enclose something into '''....''' triple quote in python, that statement is considered as a comment in python. However, if we enclose something into triple quotes and just write the statement below the function name or right above the function body, then the whole meaning changes and the interpreter does not ignore it. This is what are docstrings in python. Now let's dive into much greater details to understand DOCSTRINGS.

So let's get started......

Docstrings In Python

They are string literals that appear right after the definition of a function, method, class or module.

Example

def square(n):
  '''Takes in a number n, returns the square of n'''
  print(n**2)
square(5)

Output

25

Here,

'''Takes in a number n, returns the square of n''' is a docstring that will not appear in output

Example -

def add(num1, num2):
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add(2, 2)
    4
    >>> add(25, 0)
    25
    >>> add(10, -10)
    0
    """
    return num1 + num2

print(add(3,6))

Output -

9

In the above example as well, the statement enclosed between triple quotes is docstring.

Python Comments vs Docstrings

Comments - They are descriptions that help the programmers to better understand the code functionality and intent. They are ignored by the interpreter.

Docstrings - They are strings used right after the definition of a function, method, class, or module (like in Example 1). They are used to document our code.

We can access these docstrings using the doc attribute.

Python 'doc' attribute

Whenever string literals are present just after the definition of a function, module, class or method, they are associated with the object as their doc attribute. We can later use this attribute to retrieve this docstring.

Example -

# the docstrings in the function are not ignored just like some other strings. To put docstrings just put them at the beginning of the function definition. Do note the docstring is not like a comment that will be ignored.

#docstring should be placed just below function name or right above  function body
def square(n):
  '''Takes in a number n, returns the square of n'''
  print(n**2)
square(5)
print(square.__doc__) #using __doc__ we can call the docstring.

Output -

25
Takes in a number n, returns the square of n

Important Note - Docstrings should be placed just below the function name or right above the function body as shown in the above example.

PEP 8

It is the document that provides guidelines and best practices on how to write Python code. It was written in 2001 by Guido van Rossum, Barry Warsaw, and Nick Coghlan. The primary focus of PEP 8 is to improve the readability and consistency of Python code.

PEP stands for Python Enhancement Proposal, and there are several of them. A PEP is a document that describes new features proposed for Python and documents aspects of Python, like design and style, for the community.

Zen of Python

Long-time Pythoner Tim Peters succinctly channels the BDFL’s guiding principles for Python’s design into 20 aphorisms, only 19 of which have been written down.

Easter egg

import this    #this prints Zen of python. A short poem on coding in python which is highly relatable to any programmer

Output -

Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Resources Used

You can watch the video of Day#29 by clicking on the below link 👇👇👇👇👇

Conclusion

Thanks, guys for going through this blog post. On day #29 we learned about Docstrings and Zen of python and python document guidelines PEP 8. Learnt something interesting and fun stuff about python today.

Thank you if you read this post and have found this post useful. I hope you have joined me and are enjoying my magical journey of python coding. This is it for Day #29

See you in the next one.....


About Me

Hey Guys, I am Chintan Jain from CodeWithJain. I am a trader and content creator. I am also passionate about tech and hence wanted to explore the field of tech. I always wanted to learn to code so I watched many tutorials but procrastinated practicing coding. To get into the habit of coding consistently I am starting to BLOG with HASHNODE on daily basis.

I will document my coding journey from scratch and share my daily learnings in a blog post on HASHNODE. I hope you all will enjoy my content and my coding journey.

So what are you waiting for, smash the FOLLOW and LIKE buttons and follow along my coding journey, a step to create more beautiful digital products and empower people.