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

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

fundamentals of LLM: A story from history of GPTs to the future

Introduction: So there has been a lot of developments in LLM and I have not gone through any of it. In the coming few parts, I will talk about LLM and its related eco-system that has developed and will try to reach to the cutting or more like bleeding edge. Lets go through the main concepts first. What is LLM? LLM[1] refers to large language models; that refer to mainly deep learning based big transformer models that can perform the natural language understanding and natural language generation tasks much better than the previous versions of the models generated in NLP history. LLM models are generally quite big, in terms of 10-100GBs and they can't fit in even in one machine's ram. So, most LLMs are inferenced using bigger GPU cluster systems and are quite computationally exhaustive. What was the first true LLM? The BERTs Transformers were invented on 2017 by vaswani et al in their revolutionary paper called "attention is all you need". After that we had the BER...
Post a Comment
Read more