-3

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

  • 1
    The primary question that comes to mind is: why? You'd have to add functionality to the website to handle two completely different commenting mechanisms. Further, how do you discern between command line log output and actual code that would get commented on? The technical hurdles here seem very large (note I'm not on the SE dev team, this is however something that is not small to write out. I also don't think there's much added value to users or commenters to split comments out from the standard comments section. Circling back to the original question: why? – Thomas Ward May 13 '18 at 21:25
  • To just whether it can be done or not should me second step, because thoughts about it are not worth the time if the idea is bad in the first place. Why I tried to outline. I spent countless hours on single lines or sections with uncommented parameters or researching the meaning of some lines elsewhere. Prime example is sed/awk codewhere a simple "this replaces all old path's with the location" could make me understand a fragment a lot better. Normal use case is you have an old post, so questions to the authors are pointless. see next comment. – CatMan May 13 '18 at 21:37
  • ... An the standard comment section is often used to put code in it. You find it in many places, because people would like to add value, but they do not feel its worth an own answer (done it myself). Those comments are hardly readable. I copy&paste them in gedit to make sense of them. Also how do you point to a specific line in a comment? I can see why comments are how the are and that is fine. I just think they do not solve the things a parallel comment could. – CatMan May 13 '18 at 21:40
  • I still don't see why splitting things out and adding a completely separate comments implementation makes sense. Not to mention it's incredibly hard to make that work proper, and you have to consider that this is something that'd have to be developed network wide and adds a good bit of overhead in terms of DB, design, etc. (I'm not an SE dev, but I've done enough dev work to know the evils of these types of requests). Not to mention, but you have to change the mechanisms for how code is formatted/parsed, among other things. Not to mention that would affect plain preformatted stuff too) – Thomas Ward May 13 '18 at 21:55
  • @ThomasWard I can see that it is hard to put the implementation effort aside. I think that can be solved, but it is of course an issue. Maybe my mistake is to have tagged it as Feature-request? I would think it better be tagged as concept idea in search of feedback. Do you think it would help to remove the Feature-request tag? – CatMan May 13 '18 at 23:00
  • No, i don't think there's an issue with the tag. The community at large is allowed to raise their comments/concerns on any post, feature request or not, so that won't matter as much whether it's tagged feature-req or not. – Thomas Ward May 14 '18 at 1:59
  • @CatMan Removing the tag won't change the fack this IS a feture request. It is common for people to go "it's just a discussion man, look at the tags, i'm just starting the conversation" but I like to think the users are smarter than that and will judge what the post is based on it's content rather than the tag. – Mark Kirby May 14 '18 at 10:40
  • I'm only an expert in correcting typos, so that's why I use my time doing that – Zanna May 15 '18 at 19:28
5

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
  • Interesting. My default Firefox does not give me syntax highlighting. Do I need any plugins for that? Do I take it that you do not see added value? – CatMan May 13 '18 at 21:44
  • 1
    @CatMan You might be interested in this meta answer and its comments… – dessert May 13 '18 at 21:52
  • @CatMan code formatting is only able to be applied when a specific code tag is in use, or when provided in the proper format in the answer, as explained here and here – Thomas Ward May 13 '18 at 21:52
  • @dessert theses added links as well as the line from your comment are posts that miss their target auditorium on Meta, don't they? See my comment in the meta.askubuntu.com/a/14108/507051 post – CatMan May 13 '18 at 22:17
  • @CatMan That’s why we have a tour and a help center on main, the information is all there. – dessert May 13 '18 at 22:25
  • @dessert Please do not take offence, but I have that kind of discussion of the with developers very often. I never saw the help page. Just checked it out again and now I can tell you why. On the start page of AskUbuntu I nowhere see a help link/button. I have to scroll down 13 times with my mouse to get to the bottom of the screen. Then in a column "Ask Ubuntu" there is help with no highlight between Tour, chat contact. Did your read Douglas Adams? Every bet: count clicks now and put is as a big button on top of the page and count clicks again. They will double (at least). – CatMan May 13 '18 at 22:42
  • @CatMan Actually, there is a big button with a question mark on top of each page, containing links to the tour, the help center and meta… – dessert May 13 '18 at 23:04
  • 1
    @dessert. Your point. Not what I had in mind, bit it is there with 2 clicks. Would be interesting to see in an unbiased end user testing if what I had in mind would make a difference at all. Probably not. GUI design is full of surprises and depression :-) – CatMan May 13 '18 at 23:09
1

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...

  • Maybe if it would not make it likely that people explain their code, but it makes it more likely that other add a comment. – CatMan May 18 '18 at 14:04
  • I added an example, because I think it would look good, but found it hard to explain in words. I wouldn't why it should not be more accessible. Of course you could implement is so badly that nobody would use it. My main point is, I guess, I know why beside the mega-posters nobody is doing it. Just as an example, I would take the time to add a comment somewhere but not to write sections with copy&paste references using the very limited and tiny web editor window. And when I see with how little effort one is listed in the top ten posters, many users seem to be a lot more lazy than I am. – CatMan May 18 '18 at 15:18

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .