The world’s leading publication for data science, AI, and ML professionals.

3 Easy Steps to Folding Docstrings in VSCode

How to add documentation to VSCode data science projects without cluttering the source code or reducing readability

Photo by Mohammad Rahmani on Unsplash
Photo by Mohammad Rahmani on Unsplash

Background

Programmers using VSCode should add "docstrings" to their projects which generate the documentation for users of the code to read when they hover over it in VSCode or press Shift-Tab in Jupyter notebooks.

Programmers can also use extensions to auto-generate the docstring skeletons to save time, for instance, the excellent Python Docstring Generator which can be obtained here – https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring.

However, the Docstrings take up a lot of vertical space and when you have added a few they can tend to make the actual code less readable and harder to understand.

Having experienced this myself I wanted the best of both worlds – to generate useful and descriptive documentation without reducing the readability but when I searched online it appeared that this could not be done – https://github.com/microsoft/vscode/issues/37052

Undaunted I looked for a way to resolve this based on the articles I had read and sure enough, it can be fixed quite easily and you can have your coding cake and eat it at the same time!

The Problem

If you have the Python Docstring Generator extension installed you can simply go to the right place in your code and type 3 double quotes and the skeleton docstring will be created for you –

Step 1 – Type 3 Double Quotes

Image by Author
Image by Author

Step 2 – The DocString is Generated

Image by Author
Image by Author

Step 3 – Overtype the Defaults with the Details

Image by Author
Image by Author

We now have a nicely constructed docstring that will show up for users of our code in VSCode or Jupyter notebooks but by the time we have added a lot of docstrings in a medium sized module it starts to look cluttered and difficult to read.

The Solution

Step 1 – Fold the Args and Returns

The first step is to recognise that the auto-generated docstring does have some limited capability for folding.

If you hover the mouse over the gutter between the code line numbers and the code itself you will see a number of down chevrons which indicate where the current folds are and you will see that Args and Returns can be folded and collapsed out of the way –

Image by Author
Image by Author
Image by Author
Image by Author

This is a bit of an improvement but the documentation is still quite big and at this point you have reached the stage where the online advice, for example in https://github.com/microsoft/vscode/issues/37052 – says that folding of docstrings is not implemented, but it can be done …

Step 2 – Fold the Entire Docstring

The key to the trick is the realisation that VSCode docstring folding works by indentation, so if you manually rearrange the docstring generated by the docstring generator to indent the Args and Returns you now have the capability to fold, collapse and hide your documentation –

Image by Author
Image by Author
Image by Author
Image by Author

That is much better, but it is still annoying that it takes up 2 lines when 1 line would be much tidier.

Step 3 – Reduce it to a Single Line

The final trick is to include the closing 3 double quotes into the folding. This can be achieved by simply indenting them by an extra tab or by moving them to the end of the final part of the documentation comments which I find to be tidier –

Image by Author
Image by Author
Image by Author
Image by Author

The code now has a full docstring which will be displayed correctly in VSCode or Jupyter notebooks that has been folded and collapsed so it does not clutter up the code unless the programmer wants to click on the down chevron to re-display it in full.

Conclusion

We have seen how docstrings can provide documentation to code that will be shown to consumers of the code in VSCode or Jupyter notebooks and that the Python Docstring Generator can automatically generate the stubs.

However these docstrings cannot be folded and collapsed and quickly clutter up the code making it less readable more difficult to maintain.

The online advice appears to indicate that docstrings cannot be folded, collapsed and hidden in VSCode but actually there are 3 simple steps that enable this to be done.

Implementing these steps enables us to have our coding cake (documentation) and eat it (readability) at the same time!

Thank you for reading!

If you enjoyed reading this article, why not check out my other articles at https://grahamharrison-86487.medium.com/?

Also, I would love to hear from you to get your thoughts on this piece, any of my other articles or anything else related to data science and data analytics.

If you would like to get in touch to discuss any of these topics please look me up on LinkedIn – https://www.linkedin.com/in/grahamharrison1 or feel free to e-mail me at [email protected].


Written By

Topics:

Related Articles