Programmers frequently write human-readable comments (which are ignored by the computer) to describe certain regions of code (Figure 1).
One might, naively, expect that these comments would be separated from the main code in some fashion that would make them easy to consult (or ignore), as desired. This is how books have operated for thousands of years, with additional information in the page margins and footnotes.
But this is not how programming works! Comments are mixed in with the rest of the code. As as result, having extensive comments can make code quite hard to read, as seen in Figure 2.
Let’s re-invent the footnote! Instead of having super-long comments mixed in with the code:
- Add a footnote in the “main” part of the code. This footnote will have a unique number that links it to…
- …a matching footnote at the very bottom of the text file.
(You may have noticed that this is exactly how footnotes work in a book.)
Now, the monstrously long comments in Figure 2 are reduced to a manageable size (Figure 3):
Since these footnotes are basically equivalent to HTML links, it would be easy to make code-editing software aware that this footnote text could be displayed specially: see one possible option in Figure 4.
Crucially, the footnotes will still exist as text at the bottom of the file—we want these files to remain plain text, not some weird format that requires special editing software.
If this is too much work, it seems like a simple option would be to have a single keyboard shortcut that would collapse (or show) ALL comments in a file. Somehow, this is not a feature that exists as a built-in feature in any widespread code-editing software in 2022. Hard to believe! There are, at best, some extensions that will collapse some comments, or set the comment color to the same color as the document background (which still takes up screen space).
PROS: Allows comments to be more descriptive without impeding readability of the actual code.
CONS: Actually none? Why is this not a thing!