Solve an issue that has bedeviled programmers for over 50 years: move code comments OUT of the main body of the code and INTO the margins. Long code comments can be footnotes!

Background:

Programmers frequently write human-readable comments (which are ignored by the computer) to describe certain regions of code (Figure 1).

Fig. 1: Comments are in green (after a “#” character). Everything else is regular code.

The Issue:

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.

Fig. 2: These comments provide some useful information, but they really get in the way: Figure 1’s 24 lines of code now take up 2.5 times as much screen space!

Proposal:

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):

Fig. 3: The file is still super long (in fact, it’s even longer than before!), but the excessively-verbose comments are now placed in their own “footnotes” section.

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.

Fig. 4: In a modern editor, the footnotes could also be presented as tooltips when the user hovers their mouse over the footnote. Putting the notes in the margin would be another option: this is already how comments are handled in many collaborative (non-programming) document editors (e.g. Microsoft Word or Google Docs).

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.

Conclusion:

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!