Efficient Docstring Writing with autoDocstring in VS Code

Introduction

Incorporating docstrings and in-line comments is a great way to improve code interpretability, and it also helps reduce the maintenance cost. However, these benefits are often neglected by developers due to various type of reasons. I’m here to share a tool called autoDocstring and some tips to assist you in writing consistent docstrings more efficiently in VS Code.

autoDocstring

Developed by Nils Werner

autoDocstring is a highly useful VS Code extension that generates the preferred docstring template based on a function signature specified. The extension is loaded with several awesome features that make it a pleasure to use.

• It offers some popular choices of docstring style, including google, numpy and etc. And of course, it also supports customised docstring format.
• It automatically performs type inference for parameters and return values and populates the information in the template to save your time and effort.
• It allows a quick docstring generation by two easy commands.
• The cursor automatically focuses on and selects the first placeholder after the template is generated and you can press tab or shift + tab to navigate around.

In my preferred setting, I opt for the Google style, as it is recognised and compatible with other documentation frameworks such as MkDocs.

Demo

Here, we have a very simple function add_two_numbers() that returns the sum of two integers. To make the most of autoDocstring, it highly recommended to specify type hinting in the code, so autoDoctring can picks up the types for you. To generate the template, you need to press the command you specify. The generated template has three parts, a function summary, an arguments section and a returns section. The cursor automatically focuses on the first placeholder _summary_ after the template is generated. You can start typing straightaway and press tab to move to the next placeholder _description_.

Conclusion

By using tools like AutoDocstring, you will be able to write docstrings in a very consistent manner. Over time, it will become second nature to write a docstring for every function or class that you create. This can significantly enhance the readability and maintainability of your codebase, as well as make it easier for others to understand and use your code.