
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

Step 2 – The DocString is Generated

Step 3 – Overtype the Defaults with the Details

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 –


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 –


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 –


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].