Justin Duke asks if treating code comments like footnotes could help us understand the code in a file better. In his mockup, all the comments are hidden by default and require a click to reveal:
What a neat idea! Justin’s design reminds me of the way that Instapaper treated inline footnotes.
I guess the reason I like this idea so much is that a lot of comments don’t need to be read constantly, — they’re sort of a reminder that, “Hey, this needs work in the future” or “Yikes, this is weird and I’m sorry.” Keeping these comments out of the code makes it much easier to scan the whole file, too.
I do wonder if there could be a toggle that shows every comment, just in case you need to read all the comments in sequence rather than clicking to toggle each one.
Anyway, all this talk about comments reminds me of an absolutely fantastic talk by Sarah Drasner at JSConf this year where she discussed why comments are so dang hard to get right:
Another opinion about how to ( not) write comments: https://blog.usejournal.com/stop-writing-code-comments-28fef5272752
It’s a strong opinion, but after I started to follow this, I keep seeing an improvement on my code. It is more self explanatory than before.
Something like this might also encourage more robust comments, since you could write more information without taking up a lot of visual space in the code. I like it! The only change I would suggest would be some sort of syntax for certain comments to not collapse. Sometimes I use comments as section titles within long HTML or CSS documents, and it would be nice to display those while hiding descriptive comments about specific bits of code.
Sometimes the code is complex but do a simple stuff. In this case comments act more as short explanations then footnotes, so they must be visible.
The premise of good code style doesn’t need comments sounds great but I reality, the comments are not there to help you today but 3 years from now when you have go back to the code and understand what you were trying to do .
I’ve seen so many cases when people have incorrectly used == instead of != And you are debugging the code and you are trying to understand if they meant that or not. A simple comment like
// When the state is not empty do…
Can be a life saver.
I like the idea of putting comments into a collapsible section.
I’m actually really interested in the reverse. Something called literate programming. Think of it as writing a markdown file with code snippets inside.
https://en.wikipedia.org/wiki/Literate_programming
https://github.com/Rich-Harris/lit-node