Skip to main content

docstrings in python programming


What is docstrings?

To quote PEP 257 from python's own documentation,
"

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

"
To ease this definition out, basically, a docstring is a piece of string or a small note which is generally provided in a class, function or a method definition for informing as well as documenting important information about the class, function or the method.

There are two basic types of docstrings, which are oneliner docstrings and multiline docstrings.

How to write docstrings?

docstrings are generally literal strings and therefore you can write them within """ triple double quotes""". But there are certain rules in case of unicode or backslashes.
If your docstring information is supposed to have backslash character then you have to use r"""raw triple double quotes""". If you have unicode docstring, then you have to use u""" unicoded triple double quote""".

What to write in docstrings?

There are a few guidelines for writing docstrings.
(1) docstrings should be written in triple quotes whether it is a one liner or not. Because it helps to maintain the structure and expand the doc later on if needed.
(2) docstrings for functions and methods should be in the form of instructions and not descriptions; i.e. instead of writing "it returns sum of two digits" one should write "return sum of two digits".
(3) docstring should be a proper summary of the object you are writing it for, instead of having any coding style writing like "func(a,b) -> a+b". It is supposed to give the reader or user a proper understanding of the main idea and the tasks performed by the object; which is not visible from the raw code.
(4) For a class or a module, you are expected to write long docstrings, containing small summaries of each of the class, function and methods involved. In case of a script, the docstring should be invoked when a wrong argument is passed or a help option is invoked. These are some advanced ideas in terms of docstrings.

How to read docstrings?

A docstring is a basic attribute of any python object. If there is a documentation provided in the object's source code, then object.__doc__ will provide the documentation. i.e. in order to access the docstring of a object, you have to write
print(object.__doc__) and then if it is present then it will get printed. If there is no docstring written then it will return nothing.

Conclusion:

In conclusion, I will advise you to start writing docstrings for your modules and functions from today. If you are writing a code which is to be reused then it is your duty to make it commented and well documented so that both users and developers who are going to either use it or work on further versions of it ; do not face steep problems in terms of readability and understanding of the code because of lack of maintenance. So start writing those docstrings from today.
Labels:

Comments

Post a Comment

Popular posts from this blog

20 Must-Know Math Puzzles for Data Science Interviews: Test Your Problem-Solving Skills

Introduction:   When preparing for a data science interview, brushing up on your coding and statistical knowledge is crucial—but math puzzles also play a significant role. Many interviewers use puzzles to assess how candidates approach complex problems, test their logical reasoning, and gauge their problem-solving efficiency. These puzzles are often designed to test not only your knowledge of math but also your ability to think critically and creatively. Here, we've compiled 20 challenging yet exciting math puzzles to help you prepare for data science interviews. We’ll walk you through each puzzle, followed by an explanation of the solution. 1. The Missing Dollar Puzzle Puzzle: Three friends check into a hotel room that costs $30. They each contribute $10. Later, the hotel realizes there was an error and the room actually costs $25. The hotel gives $5 back to the bellboy to return to the friends, but the bellboy, being dishonest, pockets $2 and gives $1 back to each friend. No...
Post a Comment
Read more

GAM model : PyGAM package details Analysis and possible issue resolving

Introduction:                  picture credit to peter laurinec. I have been studying about PyGAM package for last couple of days. Now, I am planning to thoroughly analyze the code of PyGAM package with necessary description of GAM model and sources whenever necessary. This is going to be a long post and very much technical in nature. Pre-requisites: For understanding the coding part of PyGAM package, first you have to learn what is a GAM model. GAM stands for generalized additive model, i.e. it is a type of statistical modeling where a target variable Y is roughly represented by additive combination of set of different functions. In formula it can be written as: g(E[Y]) = f 1 (x 1 ) + f 2 (x 2 ) + f 3 (x 3 ,x 4 )+...etc where g is called a link function and f are different types of functions. In technical terms, in GAM model, theoretically expectation of the link transformed target variable is assume...
Post a Comment
Read more

Pyarabic: python package for Arabic language

 Introduction:  In languages which are non-english and non-european as well, NLP work has progressed slowly in the last few decades because of the lesser number of scholars working on them as well as a lack of global interest in them. But now the time has changed and people from all over the world are collaborating on these lesser explored libraries and they are building resources for working on these languages with the same ease with that of english.  Pyarabic is a package created from such a similar effort which deals with the intricate details of the arabic language and helps processing all kinds of arabic texts. While trying to learn it, being from a non-arab background, I couldn't read lots of parts of the main readthedocs site and had to work my around it. So in this blog post, I will summarize my learnings in english language, so that you can learn it and use the package with much more ease than me. [Credit where credit is due: this article heavily uses the ac...
Post a Comment
Read more