60

If I am a newbie in a language and spent a lot of time figuring out an experienced person's answer, how should I communicate this learning to other newbies?

Example: Trevor Sullivan's PowerShell regexp answer took me a couple hours to work through. Once I understood it, it was useful, so I want to help other PowerShell newbies understand what it's doing. If it was my code, I would add code comments explaining each code line (that's how little PowerShell I know), but that doesn't seem right if it's not my code. I added a (Stack Overflow) comment to the answer explaining what I figured out. Is that the right way to handle this?

15
  • 3
    Another alternative is to create a gist (or similar) with the updated code and add it in a comment on the post.
    – user1228
    Commented Jul 13, 2016 at 17:27
  • 26
    A comment seems rather a limited space to explain anything. The SO site license explicitly encourages users to create their own derived posts, as long as the original is properly attributed. Simply a link to the original post and a link to the author's profile. Commented Jul 13, 2016 at 17:30
  • If there is a code-only answer to a question that explicitly asked for clarification, I leave a comment asking the OP to add that (even if I understand the answer itself). However, for relatively old questions and answers that may be too late.
    – Jongware
    Commented Jul 13, 2016 at 17:41
  • 1
    Thanks for the gist suggestion which lets me put the code comments near the code lines that I had to figure out. Hopefully I made it clear it was my own (non-expert) interpretation.
    – KAE
    Commented Jul 13, 2016 at 17:54
  • 3
    The code is clear to me (or I can guess its intent, and can search for help if I need it) and doesn't need comments. If you edited in comments on my post, I would revert them.
    – ErikE
    Commented Jul 13, 2016 at 23:15
  • 4
    @ErikE Why would you want your code to be commentless, if it helps people? An answer should be as helpful as reasonably possible, so comments helping out along the way is a good thing. An answer you need to guess about isn't as complete as it could be. Commented Jul 14, 2016 at 21:52
  • 1
    Edit anything you want, any time.
    – Fattie
    Commented Jul 15, 2016 at 13:52
  • 1
    @TankorSmash I guess I can see your point, but I would include a note before the code that in production I would never comment my code like this--most of my code has 0 comments. Having short methods that are well-named, using Linq-to-objects instead of loops, these make code self-documenting, and importantly: accurate at all times!
    – ErikE
    Commented Jul 15, 2016 at 15:49
  • 2
    @JoeBlow Edits to other people's code are frowned on, this is not good advice in my opinion.
    – ErikE
    Commented Jul 15, 2016 at 15:50
  • 1
    Hi @ErikE it's very fair to say that many people agree with what you just said. I just can't support it though. (1) if you care about "how you look" online, as it were, you are ten years old, not a working engineer :) (2) it says in HUGE LETTERS, EQUALLY AS LARGE as "written by", who just edited it (3) information wants to be free. there's just no place for precious, "I 'own' this" thinking today. I mean it's 2016, not 2006. (4) particularly with software engineering, 100.00% of posts become utterly out of date after as little as a few months. there is absolutely no ..
    – Fattie
    Commented Jul 15, 2016 at 15:56
  • ...absolutely no 'lasting knowledge' on here. Bringing up the f###ing flash button on an iOS camera window changes constantly. "My" answer about damned iOS camera windows is worth shit in a few months. All answers (again, especially in our field) are "useless soon". For all these reasons and more, I just can't get with the "he's looking at me Mom! he editied my post!" view, you know? Heh! That's my take, @ErikE !
    – Fattie
    Commented Jul 15, 2016 at 15:58
  • 5
    @JoeBlow The issue isn't with my ego or "how I look", the issue is that with code, especially, often the person doing a "tune-up" or "correcting" doesn't understand what he's seeing and introduces an error. But change anything you like, I get updates on my phone every time anyone does anything, and if I don't like your edit I will roll it back. My answers gain points years after I created them–maybe I make higher quality answers than you do? I think you're completely off base, and that your attitude doesn't fit well here.
    – ErikE
    Commented Jul 15, 2016 at 16:08
  • @ErikE: I don't think Joe meant any offence - excessive ego certainly is a problem on Stack Overflow, but I can't see that he was explicitly accusing you of this. Please leave out maybe I make higher quality answers than you do - there is no call for that sort of thing here, since it sounds rather elitist. Be nice!
    – halfer
    Commented Jul 16, 2016 at 13:11
  • @ErikE: I am in general not keen on his answers here, nor on coarse language in general. However, I think it is good to try to rise above it - you strike me as being entirely able to. I mean well with my input, I assure you! Best wishes to you.
    – halfer
    Commented Jul 16, 2016 at 15:50
  • @halfer Did you have to be so reasonable? And call me to nobility? Sheesh! When I said "maybe I make higher quality answers" all I really meant is that I don't think my answers are worthless over time. If Joe finds that his are, then that's not about Stack Overflow in general...
    – ErikE
    Commented Jul 16, 2016 at 16:19

4 Answers 4

71

Why leave a comment where you could have made an answer?

Mostly-code answers are serviceable, but in the longer run, there's potentially a lot of value in a clear explanation of a dense piece of code. So why hide it behind a link in a tiny comment?

As Hans said, you're allowed to use other people's posts as building blocks for your own here, as long as you properly attribute the material.

Transfer your explanation to an answer here on Stack Overflow, making it clear that you are expanding on Trevor's answer. I would also strongly suggest making your explanation primarily in prose. You can include code comments as well, but I think that using plain text will help get your material across and differentiate your post.

4
  • 4
    If I am not changing what the code does, only explaining it to save other newbies time, does that justify a separate answer? I am not contributing a new approach.
    – KAE
    Commented Jul 14, 2016 at 11:49
  • 14
    @KAE no you aren't contributing a new approach but you are explaining the approach in more detail than the original author did. There is nothing wrong with 2 answers that have the same "code" solution but explain it differently. Some users will need that explanation to understand the code, and that in of itself can make the answer useful. And if you don't want to earn rep of it since it isn't your code, you can check the "Community Wiki" box when writing the answer and the answer will essentially belong to the community to use and edit as needed. Commented Jul 14, 2016 at 13:55
  • 8
    It'll be hard to find a super 0 upvote answer below a +1148 answer. Nobody will look at it. I'd edit the +1148 answer instead. In fact, I did: stackoverflow.com/a/1091953/4136325 (maybe not call me a newbie on XML) Commented Jul 14, 2016 at 13:57
  • 2
    Good point, @Thomas, but you can post a comment on the original answer linking interested readers to the new answer. And if that answer already has a substantial collection of comments you could (also) add the link to the answer itself.
    – PM 2Ring
    Commented Jul 15, 2016 at 11:15
11

Yes, leaving Stack Overflow comments on the post is the correct way to handle it.

Don't go out and edit in code comments to other people's posts, especially when you're new to the material. If you did that, you'd be putting words in people's mouth.

4
  • 9
    +1 for not "putting words in people's mouth". Comments are great for appending small bits of info, but for this situation I think a comment would be ineffective - a new answer (with attribution) seems more appropriate here.
    – brichins
    Commented Jul 13, 2016 at 21:27
  • As long as it doesn't turn into a chat. Like what I am doing right now. :D Commented Jul 14, 2016 at 13:49
  • @AfshinM.Khiabani :-D If it turns into a discussion with the answerer, they may choose to update the answer themselves. And remove the comments afterwards. Commented Jul 14, 2016 at 13:51
  • 1
    If it's a quick, one-line "Code ABC does XYZ," then, yeah, a comment might be appropriate (and OP can edit the answer to clarify, if they want,) but if it's a line-by-line explanation of what's going on, I think the suggestion to write a separate answer with attribution is more appropriate (and more useful.)
    – reirab
    Commented Jul 14, 2016 at 22:06
4

tl;dr

Don't edit the original code. Make a new answer, and link to it (in a comment) from the original answer, and vice versa. Don't hide your potentially valuable new information in a comment that links to another castle site.


Well-written code should be self-explanatory, requiring few (or no) comments, and those comments should only be to explain why the code is performing a particular action ("why" comments). Comments that explain the action itself ("what" comments) should be avoided, since a reader competent in the language should not need such comments and will just see them as clutter. ("What" comments may sometimes be required to explain the action of an obscure algorithm, including code that uses "clever" tricks for optimization reasons).

However, newbies, by definition, are not yet competent in the language, are still coming to grips with the syntax and the facilities of the language, and may have great difficulty in understanding code that looks straight-forward to experienced programmers, especially if this is their first language and they have not yet acquired the mental skills that experienced programmers take for granted. When I'm answering newbie questions I try to explain what my code does as clearly as possible in the accompanying text and I also tend to annotate my code liberally with both "why" and "what" comments, and add explanations in the accompanying text.

If someone feels that my code needs further explanation I'd prefer that they communicate with me via comments, and I'll improve my answer. IMHO, making substantial edits to someone else's answer (i.e., edits that change the original intent of the author) should only be done as a matter of last recourse.

[ Aside: If you simply disagree with an answer (and that includes believing that it's technically incorrect) then you certainly should not edit it, you should write your own answer. OTOH, if the answer is potentially dangerous due to technical errors and the original answerer is no longer around (or is not responding to comments) then it may be necessary to edit it. Of course, minor edits (like correcting typos or improving formatting) are ok, but even then I think it's more polite to submit a suggestion to the author via comments first. ]

I would not be happy with someone adding code comments to my answer, especially if they were a less competent programmer than me. :) OTOH, newbies can often relate well to the problems of other newbies, so the newbie perspective can fill in gaps that the more experienced programmer may not even notice.

So if someone wants to create a new answer that contains an annotated version of my code, with extra text and code comments designed to help other newbies, I'm more than happy for them to do that (in fact, I'd probably be a little flattered), as long as they make it clear to future readers that their answer is derived from mine. I would appreciate it if they left me a comment on my answer linking to their answer; that comment will help future readers to find their post.

If they do a good job, I'll probably give them an upvote. But if they do a bad job, be prepared for a barrage of comments and potential downvotes. :evil grin:

-2

Be cautious inserting comments into other peoples' code. If it's just one line and the code is very cryptic and the comment explains it well, it is probably ok, but making a lot of commentary is a violation of the author's intent.

In the example you give, the problem is that the code is a big, extremely cryptic blob. In a case like this, you are justified making your own answer that explains the original answer. Copy the code in the other answer, break it down and explain it in detail.

You must log in to answer this question.

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