EDIT

To make it a bit more clear where I see the advantage let me add a (very) primitive example. Its a section from an answer about a bind9 config.

a) This is the status quo today.

The reverse zones file changes to:

;
; BIND reverse data file for 172.20.x.x
;
$TTL    604800
@       IN      SOA     nefitari.autun.hom. webuser.autun.hom. (
             2017022102         ; more intuitive serial YYYYMMDDss, here ss=02
                 604800         ; Refresh
                  86400         ; Retry
                2419200         ; Expire
                 604800 )       ; Negative Cache TTL

; note: the '@'was missing from in the initial description
@       IN  NS  nefitari.autun.hom.    

100.0   IN  PTR nefitari.autun.hom. 
121.0   IN  PTR client1.autun.hom.
130.0   IN  PTR client2.autun.hom.
33.0    IN  PTR client3.autun.hom.

Here follows the text section with an explanation of the above...

The explanation may use different ways to discuss the code as described in Zannas answer.

b) With the proposed presentation it would look like this.

The reverse zones file changes to:

                                                 [hide comments]
_______________________________________________  ________________________ 
|;                                            |  |                      |
|; BIND reverse data file for 172.20.x.x      |  |                      |
|;                                            |  |                      |
|$TTL    604800                               |  |                      |
|@       IN      SOA     nefitari.autun.hom. w|  |                      |
|             2017022102         ; more intuit|  |always change that lin|
|                 604800         ; Refresh    |  |                      |
|                  86400         ; Retry      |  |                      |
|                2419200         ; Expire     |  |                      |
|                 604800 )       ; Negative Ca|  |                      |
|                                             |  |                      |
|; note: the '@'was missing from in the initia|  |                      |
|@       IN  NS  nefitari.autun.hom.          |  |here is the change,...|
|                                             |  |..when its really long|
|                                             |  |it could add newlines |
|100.0   IN  PTR nefitari.autun.hom.          |  |                      |
|121.0   IN  PTR client1.autun.hom.           |  |                      |
|130.0   IN  PTR client2.autun.hom.           |  |                      |
|33.0    IN  PTR client3.autun.hom.           |  |                      |
|_____________________________________________|  |______________________|

There is a button [show comments] as default. After pressing this the button the single code textbox is split into two textboxes. The right side shows only lines with a special tag, e.g. {{comment|here is the change}}. The ASCII graphics should show the shaded text boxes and the button.

In this example a new user has the benefit to see the whole config file (not only a fraction which may more more confusing than helpful) an immediately spot the relevant sections. A few words or a 'see 1)' could link to a comment in the text. With all that the code still is "unpolluted" from this comments. One could think of those comments as 'Meta' comments only to explain an answer but not intended to end up in the code/config.

When you have this option and its easy to use, I think people would use it. Also I think its quite intuitive to understand, even for new forum users. Obviously the smaller the screen is the more difficult are multiple windows. But I find that I often do not care about the details of long code lines where today i see scoll bars quite often, but I look at the in-code comments to understand what the whole thing does before going into details. I would find this easier to do with that separated box, especially on a tablet or laptop.

With more effort, one could tag changes to users like in the comments, but I would feel this is a bit more challenging to keep the look&feel clean and easy.

Its fine if nobody likes it, but hopefully at least we are on the same page :-)

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

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?