This is a really insightful comment. I've struggled in the past with what the purpose of commenting is. I've written some programs where comments were the majority of the code, and it was actually more difficult to read than if I'd just left it unannotated. I've also written quick-and-dirty programs that gradually turned into behemoths, left them alone for six months, and then come back to them and felt like kicking myself for not putting comments in.
I just had a crazy idea for commenting, though - I'm imagining an IDE that is built for two monitors. The left monitor is your source code. The right monitor is your comments. You wouldn't put your comments in and around the code; you'd put them into this application that would be running on the right monitor. When you select a line of source code, the relevant comments pop up on the right side. They can be as complex as you want them to be. If your class needs five pages of comments, you can put five pages of comments and not have to worry that it's going to disrupt the source code. Then, when you select something else, that comment disappears and is replaced by the comments for that line. You could even have extra monitors (or sections of that comment monitor) showing multiple things - for example, you could have the function's comments along with the line-by-line comments.
Is this crazy, or more importantly, has this been done before? I think the first thing that someone will say is that it's too much effort, but it doesn't have to be used for everything. You don't need to make a five-page comment for your for-loop, but you might for your massive class that encapsulates ten objects and has forty-five functions that modify different things.
I've never heard of showing two different view styles of the same source code document in two separate windows/monitors, but it makes sense. Perhaps this could be done with literate programming, or LaTeX packages (where you use the same file either to build the documentation or install the package), or even Javadoc and its imitators, with an IDE that lets you collapse either the comments or the function bodies. Maybe Light Table could have something like this? But if your tooling had good support for it, like being able to click on a function in the code window and make the doc window bring up that function's info, that'd be pretty nice.
I just had a crazy idea for commenting, though - I'm imagining an IDE that is built for two monitors. The left monitor is your source code. The right monitor is your comments. You wouldn't put your comments in and around the code; you'd put them into this application that would be running on the right monitor. When you select a line of source code, the relevant comments pop up on the right side. They can be as complex as you want them to be. If your class needs five pages of comments, you can put five pages of comments and not have to worry that it's going to disrupt the source code. Then, when you select something else, that comment disappears and is replaced by the comments for that line. You could even have extra monitors (or sections of that comment monitor) showing multiple things - for example, you could have the function's comments along with the line-by-line comments.
Is this crazy, or more importantly, has this been done before? I think the first thing that someone will say is that it's too much effort, but it doesn't have to be used for everything. You don't need to make a five-page comment for your for-loop, but you might for your massive class that encapsulates ten objects and has forty-five functions that modify different things.