Comments are pieces of information present in the middle of code that allows a developer to explain his work to other developers. They make the code more readable and hence easier to debug.
Inline Comment
An inline comment is a single line comment and is on the same line as a statement. They are created by putting a ‘#’ symbol before the text.
Syntax:
# This is a single line comment
Example:
Python3
def my_fun(): # prints GeeksforLazyroar on the console print("Lazyroar")# function callmy_fun() |
Output:
Lazyroar
Note: Although not necessary, according to Python there should be a single space between # symbol and comment text and at least 2 spaces between comment and the statement.
Block Comment
Block comments in Python usually refer to the code following them and are intended to the same level as that code. Each line of block comment starts with a ‘#’ symbol.
Syntax:
# This is a block comment # Each line of a block comment is intended to the same level
Example:
Python3
def my_fun(i): # prints GFG on the console until i # is greater than zero dercrements i # by one on each iteration while i > 0: print("GFG") i = i-1# calling my_fun# it will print GFG 5 times on the consolemy_fun(5) |
Output:
GFG GFG GFG GFG GFG
Docstrings
The documentation string is string literal that occurs as the first statement in a module, function, class, or method definition. They explain what can be achieved by the piece of code but should not contain information about the logic behind the code. Docstrings become __doc__ special attribute of that object which makes them accessible as a runtime object attribute. They can be written in two ways:
1. One-line docstring:
Syntax:
"""This is a one-line docstring."""
or
'''This is one-line docstring.'''
Example:
Python3
def my_fun(): """Greets the user.""" print("Hello Geek!") # function callmy_fun()# help function on my_funhelp(my_fun) |
Output:
Hello Geek!
Help on function my_fun in module __main__:
my_fun()
Greets the user.
Note that for one-line docstring closing quotes are on the same line as opening quotes.
2. Multi-line docstring:
Syntax:
"""This is a multi-line docstring. The first line of a multi-line docstring consist of a summary. It is followed by one or more elaborate description. """
Example:
Python3
def my_fun(user): """Greets the user Keyword arguments: user -- name of user """ print("Hello", user+"!")# function callmy_fun("Geek")# help function on my_funhelp(my_fun) |
Output:
Hello Geek!
Help on function my_fun in module __main__:
my_fun(user)
Greets the user
Keyword arguments:
user -- name of user
The closing quotes must be on a line by themselves whereas opening quotes can be on the same line as the summary line.
Some best practices for writing docstrings:
- Use triple double-quotes for the sake of consistency.
- No extra spaces before or after docstring.
- Unlike comments, it should end with a period.
