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