Python Basic – How to Use Comments and Doc Strings in Python

Comments and doc strings

Comments and docstrings are used in Python to provide additional information about the code and make it more readable and maintainable.

Comments are used to add human-readable explanations about the code. They start with the # symbol and are ignored by the Python interpreter. They are often used to explain what a particular section of code does, or to leave notes for future developers who may work on the code.

Docstrings, on the other hand, are special string literals that appear at the beginning of a module, class, or function, and are used to describe what the code does. They are assigned to the __doc__ attribute of the corresponding object and can be accessed using the help() function. Docstrings allow developers to create high-level documentation for their code, which can be useful for others who want to understand or use the code.

Comments in Python

Comment means some instruction about something or omitting the unnecessary block of codes. Comments can also be written with the code when writing the code. But the words of that comment do not run like the program. So writing comments with the code in this way helps others to understand that code and what can be done with that code and how it can be done can also be understood before running the code.

You must use the # (hash or pound) sign before writing any comment line in Python. Let’s look at the following example –

Example:

   # few variables below
   x = 10
   y = 5
 
   # make sum of the above two variables
   # and store the result in z
   z = x + y
 
   print(z)  # print the result
   # print (x // y)
   # another comment

Output:

   15

We have written some comments on the above program which will be understood later what has been done in this program.

Dock string

Another thing like a comment is a doc string or document string. But it is used in a slightly different way and in a more specific way. Usually, a multi-line string is written at the beginning of a function, and a comment block related to that function is written which is called a dock string.

Example:

   def greetings(arg):
       """
       Print a arg with an
       exclamation mark following it.
       """
       print(arg + "!")
 
   greetings("Hello EnableGeek!")

Output:

   Hello EnableGeek!!

This is a little different from the general comment. For example – these strings can be accessed during program runtime as follows,

Example:

   def greetings(arg):
       """
       Print a arg with an
       exclamation mark following it.
       """
       print(arg + "!")
 
 
   print(greetings.__doc__)
   greetings("Hello EnableGeek!")

Output:

       Print a arg with an
       exclamation mark following it.
      
   Hello EnableGeek!!

Through the print(greetings .__ doc__) statement of the above program we have seen the documentation of the greetings function and then used it by calling.

Module

A module is a set of code that contains a number of functions, variables, or data that can be accessed and used in another Python program. Python has many built-in modules that add a lot of essential functions. If you want to write a program for yourself, you can use some features from those modules.

If you want to use such a module in a new program, you must first import it.import MODULE_NAME like this. Under this statement, MODULE_NAME.VAR can be used to access the function or variable of that module. Let’s look at an example –

Example:

   import random
 
   result = random.randint(50, 100)
   print(result)

In the above program, we wanted to store a random number in a variable named value. That random number will be between 50 and 100. But we did not write the function of creating that random number ourselves. Instead, we have imported a random number of Python’s built-in modules and are getting random numbers using the previously defined randint function. 

The output of this program will be the same one at a time but of course, there will be a valued print whose value is between 50 and 100.

More module imports can be done. If we need certain items in a module then only they can be imported. As in the following example –

Example:

   from math import pi, sqrt, floor
 
   print(floor(23.989788))
   print(pi)
   print(sqrt(144))

Output:

   23
   3.141592653589793
   12.0

In the example above we have imported only the pi constant and the sqrt, floor function from the math module. And so, we can use these in our program. Now suppose you don’t like the name sqrt. If you want the name of the function to find the square root to be a little better. You can do the same as below –

Example:

   from math import sqrt as root_over
 
   print(root_over(144))

Output:

   12.0

Many people use MODULE_NAME import * to import all the objects of a module such as functions, variables, and constants. This should not be done at all. This is because it can be difficult to understand whether the name of a function or variable used in your code is derived from the module or created by yourself.