Python Rules Of Coding: Docstrings

in Education4 years ago (edited)

previous
Python Rules Of Coding: String literals

code-1084923_1280.png

Source

Python Rules Of Coding: Docstrings

Python docstring (documentation string) is a string literal and it can be used in any code block, i.e., the class, module, function, method definition. It provides us a handy way of attaching the relevant documentation within the code block. It describes the source code.

We generally use comments for documentation of a single line code, statement, and expressions which are usually small and not so explanatory.

Remember, this does not diminish the importance of comments use.

Docstrings are a descriptive text and better for easily understanding the functionality, the purpose of the code block.

When a programmer creates class, module, function, he/she associates the documentation for another developer to know what the purpose or what does of that class, module, function.

So that other developer who wishes to contribute to that project can easily grasp the understanding of this code block without having to read the details of the implementation.

We can use Python documentation generators like Sphinx to generate HTML documentation automatically from Docstrings.

The source code documentation (Docstrings) can be accessed using the built-in __doc__attribute or using the help function.

As PEP 257 -- Docstring Conventions, we should use
" " " triple double quotes " " " in docstrings.
r " " " raw triple double quotes " " " escape backslashes in docstrings.
u" " " Unicode triple quoted strings" " " for unicode docstrings.

We are familiar with two forms of docstrings.

  1. One-line Docstrings
  2. Multi-line Docstrings

One-line Docstrings :

class Sensor:
     def __init__(self, calc=0.0):
    “ “ “Initialize the Sensor object with the given warmth value.” “ “
    
     self.set_temperature(Calc)
     return

Notes from PEP 257 -- Docstring Conventions :

  1. Use triple double-quotes.
  2. Keep the closing quotes in the same line as with the opening quotes.
  3. No need a blank line either before or after the docstring.
def square(b):
       “ “ “ Returned argument b is squared.” “ “
      return b**b
      print(square.__doc__)    #using __doc__ attribute

Output

Returned argument b is squared.

We can also access to the docstring using the built-in help function

def square(b):
     “ “ “ Returned argument b is squared.” “ “
    return b**b
   help(square)         # using help function

Output

Help on function square in module __main__:

square(b)
    Returned argument a is squared.

Multi-line Docstring:

The form of multi-line docstrings is the same as a one-line docstring, but it is a more elaborate description.

def  my_func(dev1): 
   """ 
   Summary line. 

   Elaborated description of function. 

   Parameters: 
   dev1(int): Description of dev1 

   Returns: 
   int: Description of return value 

   """

   return  dev1

   print my_func.__doc

Output

Summary line. 

   Elaborated description of function. 

   Parameters: 
   dev1(int): Description of dev1 

   Returns: 
   int: Description of return value

______________________

Next

Operator Precedence
Sort:  

Always upvote

Once you understand how to do it it's pretty easy, isn't it?
Python as whole feels like that to me

Absolutely right, friend.

Congratulations @alrashel! You have completed the following achievement on the Hive blockchain and have been rewarded with new badge(s) :

You received more than 1500 upvotes. Your next target is to reach 1750 upvotes.

You can view your badges on your board and compare to others on the Ranking
If you no longer want to receive notifications, reply to this comment with the word STOP

Do not miss the last post from @hivebuzz:

Revolution! Revolution!

This is comprehensive. Thanks

Welcome friend