This is just an idea and I would like to see what the feedback is.

The problem

Starting Linux I've found myself many times looking through example code on this site and finding out what it actually would do.

When I am providing examples often I find it hard to explain what they do, because

• I need be as short as possible and focus on the problem
• I would like to point out stuff, e.g which bits are optional, what parameter is just an example, which one is literal. Where is a space vital, etc
• it's hard to kniw how to make it understandable to new users and experienced users at the same time. New users need single steps with many comments, while I myself prefer compact code for better overview but still good commentary.
• there is no commonly used end-of-line comment scheme.
• users may mistakenly take in code comments as part of the provided solution
• it's not easy to point to a specific code section without repeating it in the text

I myself find it important to understand what a piece of code is doing before I copy and apply that solution. Many comments say the same. Obviously, with better comments I can learn more and - more important- I get a feel for those lines where a typo could be fatal.

My suggestion

Why could we not present example code with a separate comment section? Technically it could be two synchronised text boxes, side-by-side. Left code, right commentary. The code and comments are always in sync when scrolling. The commentary is hidden by default and can be toggled with a button. The button is grayed when there are no comments. There could be markup as end-of-line comment so editing is almost no change.

This can be improved in in multiple ways, of course:

• allow adding comments as a priviledge level (IMHO better use of experts time than correcting typos :-P). Make some badges.
• Hiding comments compresses the code (because comments would not cause empty code lines)
• resizable ratio code/comment
• the comment box could utilize the space on the right column

You might say this is the wrong forum because it is a Stack Exchange coding thing. However, more than the technical details would be interested in:

• Is there added value to the users?
• Is there added value to the commenters?

What do you think?