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.