4. Comments and Documentation

These are the words or lines used in code which are ignored by interpreter while executing the lines of codes. These lines can be explanation of the line of codes which are just added for understanding the code by someone new who is working on the code or the by the coder himself who is reviewing the code after a long time. Single line comment is denoted with “#” before the start of the comment and multiline comment is written inside triple quotes.

i) Single line comment

Single line comment starts with hashtag symbol (#) and is valid till the end of the line. If we put a hashtag before the start of one comment and that comment gets extended up to the next line, then in the next line also before the start we need to enter the “#” symbol otherwise the next line will be treated as code and code with throw error. Single-line comments are more suitable for short explanations. Example of single line comment and resultant output after execution.

name = “CodingXone” # assign value to variable name
print (name) # print value stored in the variable name

Output : CodingXone

The explanation available after the # symbol shows the reader a better understanding of what task is being performed in that line.

ii) Multiline comment

Python does not have a specific syntax for multiline comments. Coders use multiple single-line comments one after another or sometimes use triple quotes (”’ or “””). Below is an example of a multiline comment.

#this is an example 
#to shows multiline comment
'''Code to print number stored in variable a'''
"""along with code to print string stored in variable b"""
a=24
b="CodingXone"
print(a)
print(b)

Docstrings are stored as attribute of the function they document unlike regular comment, means that they can be accessed programmatically. Example function is shown below:

def my_func():
    """This is an example function"""
    return

The docstring can be accessed using “__doc__” attribute:

print (my_func.__doc__)

Output : This is an example function

“my_func.__doc__” is just the actual docstring as a string, while the “help” function provides general information about a function, including the docstring. Below shown is the detailed example

def greet(name, greeting="Hello"):
    """Print a greeting to the user `name`
    Optional parameter `greeting` can change what they're greeted with."""
   
    print("{} {}".format(greeting, name))
help(greet)

Output : 
Help on function greet in module __main__:
greet(name, greeting='Hello')
    Print a greeting to the user `name`
    Optional parameter `greeting` can change what they're greeted with.

Advantages of docstrings over regular comments

Just putting no docstring or a regular comment in a function makes it lot less helpful.

def greet(name, greeting="Hello"):
    # Print a greeting to the user `name`
    # Optional parameter `greeting` can change what they're greeted with.
   
    print("{} {}".format(greeting, name))
print(greet.__doc__)

Output : None

help(greet)

Output : 
Help on function greet in module main:
greet(name, greeting='Hello')

A docstring is a multi-line comment used to document modules, functions, classes and methods. It has to be the first statement of the components it describes.

 def hello(name):
    """Greet someone.
    Print a greeting ("Hello") for the person with the given name.
    """
    print("Hello "+name)
 class Greeter:
    """An object used to greet people