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

Starting Linux I found myself many times looking through example code on this forum 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
- how to make it understandable to new users and experienced users at the same time?. New users need single steps with many comments, myself I often 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 
- its not easy to point to a specific code section without repeating it in the text

Myself I 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 be fatal.

***Here is the beef***

Why could be 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 spent experts time than correcting Typos:-P). Make some badges
 - To hide comments does compress 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 StackExchange 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?

Thanks for reading,
CatMan