Presentation of code should include explanation in a separate comment section

Question

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?

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 :-)

Answer 1

My two cents to just those two points you raised:

• users may mistakenly take in code comments as part of the provided solution

  The syntax highlighting prevents that very well, for example:

  #!/bin/bash
  a=~/dir # fill variable a
  

  Unfortunately syntax highlighting doesn’t seem to work here on meta, but on main the comment would appear greyed out if the code block was preceded by <!-- language: lang-bash -->, see e.g. this answer of mine with a real-life example of the following as well.

• its not easy to point to a specific code section without repeating it in the text

  You can use the usual formatting inside code blocks if you use the html markup, e.g.

  <pre><code>#!/bin/<i>bash</i> # italics
  a=<b>~/dir</b> # bold</code></pre>
  

  gives:

  #!/bin/bash # italics
  a=~/dir # bold

  • AU Markdown help – Inline HTML
  • What HTML tags are allowed on Stack Exchange sites?

Answer 2

I think people not explaining what code does is a much bigger problem on this site than code comments being unwieldy.

My first question about your feature request would be does it make it more likely that people will explain their code?

My second question would be does it make the explanation more accessible?

My third question would be does it look good?

I think the answers to all these questions will be no. I'm particularly concerned that it will be very unwieldy on all but the most mahoosive screens, won't show up at all on mobile devices, and will be difficult to input.

---

Here are a few bonus notes on commenting/explaining styles and techniques, in addition to the excellent points made by dessert:

• Don't worry about the explanation making your answer longer. Let it be as long as necessary for optimum clarity. Not all answers need to be beginner level, but you can link to beginner-level resources in an answer targeted at more experienced users to make it more accessible.

• Where a series of commands needs to be entered, put the explanation of each command before or after the code line, not in code format.

• I write answers that use sed, and the explanation is usually many times longer than the code, so I write it in a section below, like this. Commands using other concise languages and utilities like find can be commented this way too. (It is possible to write sed and other tiny scripts in a way that nicely accommodates end of line comments, like this).

• For languages that don't have such compact commands, comments can be slotted in between code lines (like, you know, in real life). You can also write a separate line-by-line or section-by-section explanation to keep the code itself clean.

Be creative with the tools we have available, in other words. I've never written code in an answer and felt that there was no way to add a suitable explanation to it. SE pretty much has this side of things down imho. When you request a proper table format, I'll be upvoting...