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

Mastering SQL for Data Science: Top SQL Interview Questions by Experience Level

Introduction: SQL (Structured Query Language) is a cornerstone of data manipulation and querying in data science. SQL technical rounds are designed to assess a candidate’s ability to work with databases, retrieve, and manipulate data efficiently. This guide provides a comprehensive list of SQL interview questions segmented by experience level—beginner, intermediate, and experienced. For each level, you'll find key questions designed to evaluate the candidate’s proficiency in SQL and their ability to solve data-related problems. The difficulty increases as the experience level rises, and the final section will guide you on how to prepare effectively for these rounds. Beginner (0-2 Years of Experience) At this stage, candidates are expected to know the basics of SQL, common commands, and elementary data manipulation. What is SQL? Explain its importance in data science. Hint: Think about querying, relational databases, and data manipulation. What is the difference between WHERE ...
Post a Comment
Read more

What is Bort?

 Introduction: Bort, is the new and more optimized version of BERT; which came out this october from amazon science. I came to know about it today while parsing amazon science's news on facebook about bort. So Bort is the newest addition to the long list of great LM models with extra-ordinary achievements.  Why is Bort important? Bort, is a model of 5.5% effective and 16% total size of the original BERT model; and is 20x faster than BERT, while being able to surpass the BERT model in 20 out of 23 tasks; to quote the abstract of the paper,  ' it obtains performance improvements of between 0 . 3% and 31%, absolute, with respect to BERT-large, on multiple public natural language understanding (NLU) benchmarks. ' So what made this achievement possible? The main idea behind creation of Bort is to go beyond the shallow depth of weight pruning, connection deletion or merely factoring the NN into different matrix factorizations and thus distilling it. While methods like know...
Post a Comment
Read more

Spacy errors and their solutions

 Introduction: There are a bunch of errors in spacy, which never makes sense until you get to the depth of it. In this post, we will analyze the attribute error E046 and why it occurs. (1) AttributeError: [E046] Can't retrieve unregistered extension attribute 'tag_name'. Did you forget to call the set_extension method? Let's first understand what the error means on superficial level. There is a tag_name extension in your code. i.e. from a doc object, probably you are calling doc._.tag_name. But spacy suggests to you that probably you forgot to call the set_extension method. So what to do from here? The problem in hand is that your extension is not created where it should have been created. Now in general this means that your pipeline is incorrect at some level.  So how should you solve it? Look into the pipeline of your spacy language object. Chances are that the pipeline component which creates the extension is not included in the pipeline. To check the pipe eleme...
Post a Comment
Read more