146

I have edited and added explanations to code-only answers to make them clearer.

Example:

Is this OK, or should I ask the answer author to edit and add an explanation themselves?

34
  • 147
    It is not scalable to fix the posts, we must find a way to fix the contributors. Commented Feb 21, 2022 at 0:41
  • 69
    Don't do this. It can very, very easily go against the OP's original intent.
    – user17242583
    Commented Feb 21, 2022 at 1:33
  • 32
    @richardec I disagree. Some cases are clear. A code does one thing, regardless of the OP's intentions.
    – ㅤㅤㅤ
    Commented Feb 21, 2022 at 9:38
  • 96
    Consider this "code": I have a banana. Now explain whether this is due to an apple shortage or a banana surplus.
    – MonkeyZeus
    Commented Feb 21, 2022 at 13:55
  • 40
    @MonkeyZeus what?, can you please explain your self. Commented Feb 21, 2022 at 13:56
  • 96
    @FaraazKurawle Exactly. Only I can explain my code.
    – MonkeyZeus
    Commented Feb 21, 2022 at 14:41
  • 48
    To stay with the banana example, any domain expert on bananas should be perfectly able to understand the code and explain it. So any monkey should be able to make an edit there. If only the original Fruit Salad maker can explain what he/she did there and didn't ... then the code is probably useless. Commented Feb 22, 2022 at 9:25
  • 9
    @RyanfaeScotland All you are doing is pointlessly repeating the effect of the code on the program state, a la useless/redundant comments. You are not explaining it in terms of the abstract/application state. Such an explanation is not determined by the code & should be judged by votes after posting. (Your banana example is misleading: in the original banana comment we don't know the import of "I have a banana"; bananas being part of the real world, it might seem like you are giving an abstract/application explanation, but your analogy changes having a banana to be mere program state.)
    – philipxy
    Commented Feb 22, 2022 at 9:44
  • 35
    @philipxy the comments aren't useless/redundant to the future readers who aren't domain experts and don't understand what the code does. Q: "How do I split a banana?" A: Knife.Slice(banana, 1, 6). If that was all the answer was can you tell me what Knife.Slice does? Presumably it splits a banana, but what do the parameters do? An edit to add that info is useful. Edit: "Knife.Slice takes the item you want to slice, how many of them and how many pieces you want each sliced into. In this example it would return an array of 6 BananaSlices. You can read more here: official docs" Commented Feb 22, 2022 at 11:06
  • 6
    @philipxy I still don't understand where you are coming from. If you want to explain it further I'll consider it further but equally happy to leave it there and accept we disagree but have both put our thoughts forward. Commented Feb 22, 2022 at 11:28
  • 5
    @Michael likely because of the recent question What was wrong with this suggested edit, which added an explanation for the code in an answer? getting an answer that is almost diametrically opposed to this question's consensus answer.
    – zero298
    Commented Sep 14, 2022 at 14:24
  • 5
    @Michael because some people have decided to refuse the consensus established here. I featured to let the community hash this out one last time, in whatever direction that may be Commented Sep 14, 2022 at 14:25
  • 9
    @ZoestandswithUkraine I count 88 votes in one answer for not explaining, and 121 votes spread across 5 answers for explaining. I wouldn't call that a consensus, and certainly not a consensus in favor of not explaining. Commented Sep 14, 2022 at 15:35
  • 7
    A lack of excessive answers defending one side is NOT equivalent to saying the consensus for that side doesn't exist. At best, it means one side has far more to say than the other. I don't understand why the definition of a consensus seems to be so heavily disputed as well, but this doesn't even get close to any border territories. The answer against explanations sits at 72% approval, which is over a majority and a two-thirds supermajority. Consequently, it is the consensus. That's how (direct; indirect is more complicated because representatives) democracy works. Commented Sep 14, 2022 at 16:13
  • 9
    If you disagree with the consensus, then now is your chance to change it. That's the other side of a direct democracy; decisions can be changed if there's a flip in which side has the majority, and that happens regularly in real democracies. But you don't get to change the definition of what a consensus is. 72% in favor is 72% in favor regardless of where you stand, and regardless of which side that 72% benefits Commented Sep 14, 2022 at 16:15

11 Answers 11

115

Is this OK, or should I ask the answer author to edit and add explanation themselves?

You should preferably let the author do the editing and explaining, so ask for it first. But in case the author doesn't do it and you're quite sure you know what you're doing and you use comments only where comments are useful, then go ahead and do it.

I say this because the idea in philipxy's answer ("Post your own answer, giving credit for their code.") won't work in my opinion.

I could do that and add another answer saying something like "The code in that other answer is nice but poorly documented, here it is again with some documentation" but that would result in fragmentation and duplication of content as well as an increase of the number of very similar answers, which is not desirable. Yes, there is a risk that such edits would break something but that risk is outweighed by the disadvantage of having lots of similar pieces of content clogging the system if we wouldn't make the edits and post additional answers instead.

Therefore it's either the original author that is doing the documentation of the code, or you, or nobody. In case the original author is gone or not reacting, it's either you or nobody. Stack Overflow is a collaborative effort. That's why I prefer that somebody does it. Of course there is a risk that quality actually goes down, not up, so you have to be really careful.

17
  • 6
    SO answers are CC-BY-SA; you can copy (with attribution) the code into your answer to go with the explanation. I agree that editing an explanation into answer is a good thing, especially on questions with lots of existing answers already (where a new one won't get much attention), especially when the answer in need of explanation is the highest voted. But your suggested reason of distance between answer and explanation isn't a show-stopper at all; the actual problem is vote totals for a fresh answer and being buried. Commented Feb 21, 2022 at 9:15
  • 4
    @PeterCordes For fun, let me just try to take the idea to the extreme :): We could regard answers as extremely lightweight and spawn lots of similar answers (once again with more explanation, ...) and then show people all these answers and they have to read them all and then cluster them and compare within a cluster. Then we could pick the top of each cluster, discard the rest and again spawn new similar ones. Kind of like evolutionary optimization algorithms do. Main problem might be the explosion of number of answers. Commented Feb 21, 2022 at 12:48
  • 18
    ... yeah, I have to go with this answer. In the interest of reducing duplication and fragmentation, just fix the damned answer. The implication here is that the code is actually good after all, otherwise why are we fixing up junk?
    – Gimby
    Commented Feb 21, 2022 at 17:20
  • 5
    @Gimby Yes, the scenario is that someone provides good but unpolished content. Adding documentation by a domain expert I would still regard as polishing. Some contributors know their trade but are too lazy to really make their contributions perfect. Commented Feb 21, 2022 at 20:20
  • 5
    @Trilarion: Yes, an explosion of answers, and duplication / fragmentation, is the actual problem with the "post your own answer" suggestion. Copying the code into an answer with explanation is not great, only somewhat less bad; I'm not advocating it, just pointing out that the reasoning in your question seems like a straw-man argument because there's no need to create that problem. Your points in your first comment are the actual reasons that should be in your answer. TL:DR: I like your conclusion that edits are good, but other parts of this answer were lacking. Commented Feb 21, 2022 at 20:32
  • @PeterCordes Thanks for the comments. I think you're right and tried to reformulate the central part. If that is not sufficient for you, you can submit an edit because I'm basically through with it and do not know how to better word it. Commented Feb 22, 2022 at 9:20
  • 3
    Looks good to me now; upvoted as the best explanation for why philipxy's answer is not good, and the voting on this meta question baffles me. I expected some support for the "never touch other people's answers" position, but that much support for such an extreme position seems crazy to me. One bit reason SO doesn't suck is that others can tweak and maintain highly-voted answers on existing questions, especially if the OP isn't doing it. It's not much of a stretch to assume their intent doesn't include being wrong or unhelpful. Commented Feb 22, 2022 at 10:10
  • 2
    "as well as an explosion of the number of very similar answers" This is an unsubstantiated exaggeration, the site is premised on individuals giving their own take on answering.
    – philipxy
    Commented Feb 22, 2022 at 10:15
  • 2
    @philipxy Explosion was indeed too strong. Nobody knows what would happen, would we consequently open up new answers whenever we see something that needs improvement and might change the intent. Changed to "increase" which is a more neutral description of what would likely happen. Commented Feb 22, 2022 at 10:37
  • 3
    @PeterCordes "One bit reason SO doesn't suck is that others can tweak and maintain highly-voted answers on existing questions..." Not sure many people see the editing feature as so important. If you asked around I guess that most people see voting on different answers as the key element. And that requires answers, not necessarily edits to them. It's interesting to see that Wikipedia is for example going the complete other way with only one version of each article. It's all about different ways to collaborate. There seem to be many different collaboration modes possibly that kind of work. Commented Feb 22, 2022 at 10:41
  • 4
    @philipxy "This is an unsubstantiated exaggeration" it is not, it happened and still happens when something is popular.
    – Braiam
    Commented Feb 22, 2022 at 11:38
  • @Braiam nice read. I like that, "answer cannibalisation". We should use that term more often.
    – Gimby
    Commented Feb 23, 2022 at 10:29
  • 11
    Stack Overflow is a collaborative effort - but not a collaborative reward.. There is nearly no recognition for those poor souls who toil to make the advice better, wiki style and they're much more educative heroes than the FGITW who sling a code-only answer in quick quick to bag the unicorn points..
    – Caius Jard
    Commented Feb 23, 2022 at 13:34
  • 2
    @GaiusJard You're right and I also mentioned this on this page. But then, the reward is completely the satisfaction of a job well done, a shining answer for example. The reward is not the unicorn points (at least I hope it isn't). Commented Feb 23, 2022 at 14:02
  • 3
    As someone who usually comes to SO with more questions than answers, browsing many functionally identical answers is a frustrating step in the pursuit to find an answer that works for me. It reminds me of when you Google "how to fix x issue on device y" and get those websites that have a hundred copies of the same issue page with only the name of the device changed, but the 'fix' only actually works on one or two devices, if at all. Commented Sep 19, 2022 at 2:14
134

No, you should not insert explanations into code-only answers.

An edit is to clarify the poster's intent. If they didn't explain, you are communicating your explanation, not theirs. And changing the author's intent is an edit rejection reason. And you are rewarding the posting of a fundamentally poor post. Post your own answer, giving credit for their code. Downvote and/or comment for clarification on their post.

https://stackoverflow.com/help/review-suggested-edits:

Basic workflow

  • Reject if the edit is unnecessary, destructive, or counter to the original author’s intent.

https://stackoverflow.com/help/editing:

Common reasons for edits include:

  • To clarify the meaning of the post (without changing that meaning)

N.B. However in typical Stack Overflow unclear documentation fashion, it isn't actually clear whether the preceding is actually a limitation on the general advice:

When should I edit posts?

Any time you see a post that needs improvement

69
  • 60
    I agree with this especially for brand-new answers. But I can think of some possible exceptions, like if the answer is old and popular, there are a lot of other answers, the answerer is inactive, and/or the explanation is short and widely-accepted. Then it's best to put the explanation where more people will see it.
    – wjandrea
    Commented Feb 20, 2022 at 23:24
  • 23
    What if a mega-high repper refuses to explain the most simple posts? What if they are habitually demonstrating that it is completely okay and can earn unicorn points with code-only answers (an answer accompanied by a meaningless quote in relation to the answer and requests for question clarification is still a code-only answer)? I've plead multiple times for the prolific contributor to role model better posting behaviors but they adamantly refuse. And they still get upvotes. stackoverflow.com/a/71134862/2943403 Downvotes do not deter high reppers. Commented Feb 21, 2022 at 0:39
  • 46
    Downvoting a correct answer that has no explanation "does not work" as a means to improve content. Commented Feb 21, 2022 at 1:04
  • 10
    In my experience, down-voting code only answers is fairly effective. Particularly so if the poster realizes they are getting down-voted because of the lack of explanation. But keep in mind that code can also be self-explanatory in many cases.
    – Lundin
    Commented Feb 21, 2022 at 7:30
  • 24
    I think you're over-interpreting "intent". If they don't like the explanation you added, they can always roll it back if it turns out to be wrong, or if their intent was to post a worse / lazy answer. Adding explanation for how/why a given piece of code is a good answer is a good thing if you're confident you understand how it works and any relevant nuances. That's the relevant factor, although I agree with your suggested course of action of posting your own answer, except in cases of old highly-voted answers when there are many other answers, as @wjandrea said. Commented Feb 21, 2022 at 9:09
  • 24
    I frankly don't care what their intent was, if they didn't care about their answer enough to post literally any explanation. Or I'm satisfied with assuming their intent was the ideas demonstrated in the code posted. If such an answer is old and highly voted, improving it seems like the best course to me. (Again, when I'm sure I understand the question and answer well enough to not accidentally make it worse.) Edits bump the question, so if I did mess something up, someone else should notice. Commented Feb 21, 2022 at 9:12
  • 8
    @mickmackusa If more answers makes the page worse, that's a problem with the UI, not with the system. But I don't think it gets worse. The highest score answer floats to the top, and people only look downwards if that isn't sufficient.
    – Passer By
    Commented Feb 21, 2022 at 12:27
  • 20
    Upvotes lie. I have seen plenty of highly upvoted answers that are incorrect, inappropriate, and misleading. The less scrolling a researcher needs to do, the better. It is not too much to ask for contributors to explain their solutions EVERY TIME. Code-only answers are the most selfish way of contributing. Commented Feb 21, 2022 at 12:28
  • 22
    I am so bored of trying convince people that explaining snippets is more beneficial than not explaining. I really can't be bothered trying to see eye to eye with lazy contributors who just post "try this" snippets and walk away. The behavior is so myopic. Commented Feb 21, 2022 at 12:34
  • 17
    The solution: annoy code-only posters until they either change or go away. Either way, Stack Overflow wins. SO is substantially huge, it doesn't need more contributors or more contributions. It actually needs fewer and better contributions. There is far too much noise and redundancy here. Commented Feb 21, 2022 at 12:39
  • 54
    This post goes against one of the basic tenets of the site: All contributions are licensed under Creative Commons, and this site is collaboratively edited, like Wikipedia. If you see something that needs improvement, click edit!
    – Braiam
    Commented Feb 21, 2022 at 13:19
  • 14
    I don't mean this in a bad way, but to me this reads like "we can't evaluate things on a case by case basis, better to have an unfortunate, but easily enforceable rule than to trust editors". It's OK to edit out "thanks" because there's no judgement call (you could make a regex for that). It's not OK to fix anything of consequence, because that takes judgement calls, and expertise. Not unlike how likes promote clickbait content on Youtube, voting is optimizing for... something, but is it really on "your side"? Why put so much faith in votes? Are you sure you want to tune out experts?
    – jrh
    Commented Feb 22, 2022 at 3:10
  • 16
    @philipxy is not that you can, you are explicitly encouraged to. SE doesn't have unclear or contradictory instructions. SE only writes what is in the help center. Follow that guidance alone and you will find it very consistent. They only say "respect the author" and "don't change meaning". They do not say "if there's something that needs clarification, do not edit it". In fact, they go the extreme opposite "Common reasons for edits include: [...] To clarify the meaning of the post". The only sources of inconsistency appear when you include meta discussions. Ignore them.
    – Braiam
    Commented Feb 22, 2022 at 11:35
  • 38
    I wholeheartedly disagree with this. If the code is correct, you're not changing the author's intent, you're simply explaining how the code works. There's zero reason not to do this.
    – Clonkex
    Commented Feb 22, 2022 at 21:10
  • 7
    @philipxy It's interesting how you are cherry picking the advice in the help center and then act confused "it isn't actually clear whether the preceding is actually a limitation on the general advice". The thing you copied is ONE example of COMMON reasons to edit a post. Not THE reason to edit a post.
    – Alex
    Commented Feb 23, 2022 at 13:08
94

Absolutely you should help make Stack Overflow better.

I take every opportunity to make Stack Overflow better.

  • I format.
  • I add references.
  • I improve.
  • I clarify.
  • I reformat.
  • I add comments.

Because I want Stack Overflow to be the best it can be.

  • I joined SO the day after launch: 2008-09-16 14:53:25.
  • fourteen years, and 230k reputation later, I still hold to that altruistic goal

Please continue to help improve Stack Overflow; especially as a check against the people who insist "it's not our responsibility to make Stack Overflow better".

It's not our responsibility to make Stack Overflow better, it's our privilege!


Remember that Stack Overflow was created as a combination of Wikipedia and Reddit. People can post and edit answers, and other people can vote on those answers.

Saying you shouldn't step on someone else's answer-toes, is like saying you shouldn't edit a Wikipedia entry because someone else already typed one in.

No, you should make edits to improve the sum total of all human knowledge.

7
  • 15
    I think the conflict here is rather about some more subtle lines. There is basically one camp that says, please do not edit pieces of content substantially because we are afraid you'll break things or start edit wars, rather create your own piece, even if that results in lots of non-perfect pieces. And there is the other camp that says we all collaborate and work on content together creating a smaller number of pieces which are more polished, even if that means that we sometimes break things or start edit wars or do not get rep for our services. In short: it's all about the way we collaborate. Commented Feb 22, 2022 at 9:09
  • 10
    There's probably something to be said here on whether one should give a man an edit or teach them to edit. There are lots of ways to make something better, and not all of them lead in the same direction. Commented Feb 22, 2022 at 12:11
  • 13
    @Trilarion "or do not get rep for our services." -- I'd honestly pay rep to fix some of these posts. I'm tired of writing 1 paragraph explanations in emails and internal docs saying "don't do this because" to try and preempt people reading a wrong popular post on SO. I've got the "bad SO post" wall of shame for almost every tech / language I use.
    – jrh
    Commented Feb 22, 2022 at 13:25
  • 4
    @MisterMiyagi actually it leads to the same place: a better content. We don't really care how you make better content, we want people to make better content whenever possible.
    – Braiam
    Commented Feb 22, 2022 at 16:58
  • 1
    @Braiam search for answers, order them by score reversed. Then just keep on scrolling until you find the little utopia the current approach has the manpower to sustain. Commented Feb 23, 2022 at 6:36
  • 3
    But as a combination of Wikipedia and reddit, it is NOT Wikipedia OR reddit. This answer should acknowledge that honoring the OP's intent is part of culture while rejecting the concept that an OP who posts only code couldn't possibly agree with an explanation of their own code. Commented Sep 14, 2022 at 19:42
  • 1
    @IanBoyd You've previously been told not to include that quote; the same thing applies to comments. Stop taking stuff out of context Commented Feb 10, 2023 at 16:30
57

Yes, so long as the code is good and you fully understand it, there's no reason not to add an explanation. You're not changing the author's intent; you're simply explaining how the code works. You're improving the answer, which is a good thing.

Some people have suggested that it's better to add your own answer but give credit for the code. I disagree. All this does is add clutter and duplication. We're not here to win at the game of points; we're here to provide high quality answers to high quality questions collaboratively. If the code is already good, just add the explanation of how it works.

If the code is bad, don't bother. It's never worth polishing a turd.

2
  • 2
    "we're here to provide high quality answers to high quality questions collaboratively" The problem with that is that if many people disagree with this, they will start undoing these edits and we will not be able to collaborate in such a way. We have to come to a mutual agreement, otherwise we will work against each other. If we truly say that substantial edits cannot be made then there is not much way to collaborate on single pieces of content. This is a fundamental difference about how we can collaborate and it should be discussed more. For the record, I agree with your answer. Commented Feb 23, 2022 at 11:41
  • 8
    @Trilarion Sometimes I get the impression that a lot of people would be happy if it were no longer possible to edit answers created by someone else. (The wiki-like openness to edits is an integral part of how the site is meant to work, so I agree with you and Clonex.)
    – duplode
    Commented Feb 23, 2022 at 13:53
42

I reject the currently accepted answer and would present a (nearly) opposite opinion.

Yes, you should add explanations to code-only answers, when you believe the code is not self-explanatory, or when readers would benefit from a natural-language explanation of what happens in the code.

Edits serve different purposes, not only a clarification of the poster's intent. And while a poster has "primal" rights on their post - once it is published, it is a community resource, and should be polished and improved if possible. If an author didn't explain, you are communicating your explanation, not theirs, with your edit - but this is ok, as SO is a collaborative Q&A platform. We improve and rephrase questions, and answers, all the time. It does not matter than your edit might be interpreted as "rewarding a poor post" - rewarding or penalizing user actions is ever a secondary goal to curating more-useful questions and answers.

The exception to the above is when your prospective edit would go against the poster's intent, or is clearly separate and distinct from the original answer; in such cases, a different answer should be posted, and the post should not be edited to make such a change.

It is of course legitimate to downvote and/or comment on a post lacking a proper explanation; and many people prefer doing that. But helping out by adding the explanation is just as legitimate; and if the original poster believes the edit is not in-line enough with their intent, they can alter it, or at worst, remove it - and that is also legitimate.

PS:

  • When making significant additions to a post, like an explanation of a code-only post, make sure you avoid editorialization, jokes, cultural references, examples from your own personal experience, etc. While those may be appropriate for your own post, they are less/not appropriate for posts originally by someone else, even when the post is marked as having been edited, as they are too likely to diverge significantly from the author's intent.
  • @anatolyg gives the useful advice of waiting a while before adding explanations, as the original author might be planning on doing just that.
15
  • 2
    "not only a clarification of the poster's intent" Yes but they must nevertheless preserve the poster's intent & you contradict this. Post your own answer with credit.
    – philipxy
    Commented Sep 11, 2022 at 15:35
  • @philipxy: I disagree that I contradict this, and I explicitly say that additions must meet that criterion. Will even emphasize that sentence.
    – einpoklum
    Commented Sep 11, 2022 at 15:36
  • 1
    You are adding content that is not the poster's. I'm done.
    – philipxy
    Commented Sep 11, 2022 at 15:37
  • 8
    I won't consider adding an explanation as going against posters intent, I would consider it as enhancing their intent @philipxy Commented Sep 11, 2022 at 15:38
  • 5
    @philipxy: Indeed, adding content that is not the poster's. If the content improves the answer, and doesn't belong in a different answer (like an explanation of someone's code snippet) - that's great.
    – einpoklum
    Commented Sep 11, 2022 at 15:38
  • 26
    This site is a wiki. Everything here is collaboratively edited. Of course edits are adding content that isn't the poster's. There's nothing wrong with that. That's literally the whole reason why we allow edits. Adding content that the poster is likely to abhor is probably wrong, which is why we have the "respect the author's intent" guideline, but nobody is going to be upset that their answer got better by having an explanation added into it.
    – Cody Gray Mod
    Commented Sep 11, 2022 at 15:42
  • @CodyGray "edits are adding content that isn't the poster's" but they should preserve the the author's intent, which others don't know. Except you think you & others you bless do. "This comment thread is a litany of rationalizations oblivious to protocols where everybody thinks of course their explanation is appropriate & merits the high upvotes that make the post the kind that excuses this treatment instead of just acting in accordance with the protocols that allow answers to get appropriate reactions." "content that the poster is likely to abhor" is an irrelevant straw man.
    – philipxy
    Commented Sep 11, 2022 at 15:50
  • 21
    The fact that we get people to review the edits (these reviewers can assess consistency with the author's intent) and that we give the author the ability to roll back the edit if they think it is inappropriate (the author is even notified of edits to their posts so they can review them) both serve as adequate checks-and-balances against any perceived issues. There are no "protocols", as you put it. It's been in the Help Center since time immemorial that this site is a collaboratively-edited wiki, the edits should be substantial (not trivial), and should make the post better.
    – Cody Gray Mod
    Commented Sep 11, 2022 at 16:01
  • 23
    These these edits are good is both consensus and long-standing policy since nearly the launch of Stack Overflow, as attested by all of the discussion and FAQ about this that are now over on MSE (which used to be MSO). What's newly-invented here is @philipxy's answer to this question, which doesn't represent consensus or long-standing site policy, but runs completely counter to what was the motivating vision of a Stack Exchange Q&A site. No author ever intends to post a low-quality answer, and even if they do intend this, I'm perfectly happy with our being inconsistent with that intent.
    – Cody Gray Mod
    Commented Sep 11, 2022 at 16:03
  • 1
    @CodyGray did you mean to start that last comment with "That" instead? Commented Sep 11, 2022 at 20:54
  • 6
    To me, a maximally useful and helpful Stack Overflow is a much more worthwhile goal than "preserving posts exactly as they were written plus stylistic grammar/formatting", which is just silly and bureaucratic. Yes, "refactoring" may sometimes break things, but that's what we have numerous tests and code reviews for. Also, it's usually not complete beginners that are doing the refactoring anyways. Commented Sep 14, 2022 at 18:32
  • 4
    This is clearly correct. Adding clarification to an answer is matching the poster's intent. If your clarification contradicts the code, then you aren't matching the poster's intent. Commented Sep 20, 2022 at 0:13
  • 3
    Yes, @RobertLongson. And that would be a good edit for someone to make, if it were possible to edit comments, because it improves the clarity and readability of my comment without changing its intent. (As a moderator, I can edit comments, but I'm choosing to leave this one as an object lesson in the merits of editing.)
    – Cody Gray Mod
    Commented Sep 20, 2022 at 7:46
  • 3
    @CodyGray I think your commentary here is thoughtful and revealing about the site philosophy. Would you consider adding a complete answer with it? Commented Sep 23, 2022 at 1:16
  • 1
    "rewarding or penalizing user actions is ever a secondary goal to curating more-useful questions and answers": Exactly on the money. Upvoted. Commented Sep 28, 2022 at 19:10
16

Explanations for code are welcome. Some people are too lazy to write explanations; others think their code is so clear it doesn't need any explanations; in both cases, explanations can only make the post better (maybe not by much, in second case).

Keep in mind that some people write code and decide to add explanations later; in that case, your edits will conflict, which will make a mess. When I decide to explain someone else's code, I make sure a few days have passed first. But I am not sure this is the best way to prevent conflicts.


As noted in comments, make absolutely sure your explanation is correct. You should only post correct things in general, but when editing someone else's post in particular, it's doubly important: you risk changing author's intent and lowering the quality of the answer. If unsure, post explanations as your own answer, attribute the code and let the community vote.

8
  • 56
    "explanations can only make the post better" - only if the explanations are right ;)
    – user17242583
    Commented Feb 20, 2022 at 15:48
  • 31
    For those people who are too lazy to write explanations, it's often helpful to write a comment letting them know that code-only answers are discouraged on SO, and giving them a link to how to answer. Commented Feb 20, 2022 at 16:15
  • 10
    Given that OP can only suggest edits, this could risk getting them rejected as Conflicts with Author’s Intent.
    – BSMP
    Commented Feb 20, 2022 at 23:00
  • 5
    so "people who are too lazy" will be encouraged to continue being "too lazy" (even getting more reputation) Commented Feb 21, 2022 at 7:02
  • 12
    Not sure why this got so many up-votes, since editing other people's posts to insert potentially subjective comments is simply against edit policies. Such edits will get rejected since they might change the intent of the post, making it seem like the poster said things they never said.
    – Lundin
    Commented Feb 21, 2022 at 7:27
  • 8
    @Lundin because it's one of the basic tenets of the site: All contributions are licensed under Creative Commons, and this site is collaboratively edited, like Wikipedia. If you see something that needs improvement, click edit! Adding explanations is an improvement, whatever your misgivings are.
    – Braiam
    Commented Feb 21, 2022 at 13:19
  • @Lundin For an example of changing intents of posts see Git question with very nonlinear history: Answers cannibalizing each other into redundancy. The Git question referenced therein had 10 answers and over the years all these answers became more and more similar by edits from different people, certainly changing the intent of the original content creators. Should the intent-changing edits to the answers by non-original creators maybe be undone? Commented Feb 21, 2022 at 15:53
  • 2
    @Trilarion all those answers should simply be deleted.
    – Braiam
    Commented Feb 21, 2022 at 16:59
10

There isn't a one-size-fits-all approach. Consider whether your changes would really make the answer more clear, or actually be a new answer outright.

  • Would your addition offer a small improvement, for example point out a language-specific feature or how some common trick applies?
    An edit is suitable for that.

  • Would your addition offer a significant contribution, for example explaining the approach from the ground up or increasing the answer size considerably?
    A separate answer is suitable for that.

  • Does your addition make the answer viable to begin with, for example because the question asked for an explanation instead of just code?
    The downvote button is suitable for that.

5

Yes.

Code is communication. Mainly to the programmer themselves later, or to other programmers. Its function is important, but what it says is why we use programming languages and not raw bits to program.

Taking pure code and explaining it is not going against the author's intent, and clarifies the answer, unless the intent was "confuse readers". And if it was, then we can safely ignore that intent.

You can explain the pure core poorly, and that isn't kosher. But that is why we have reviewers. Just don't do a bad job of it, and if you do do a bad job of it, swallow your ego and let it be fixed.

You are also free to take their code, write your own clarifying answer based on it, so long as you attribute where the code came from.

6
  • "You are also free to take their code, write your own clarifying answer based on it, so long as you attribute where the code came from."—this is very much the better route. That way questions about whether the change helped or hurt can be resolved naturally.
    – jthill
    Commented Oct 7, 2022 at 7:07
  • @jthill Naw; you appear to have faith in voting. Editing is pretty much consensus based, and taking code-only and adding a good explanation is both obvious to subject matter experts and honestly works. Sure, jt means most review queue people should hit "skip" but that is true a lot of the time. Commented Oct 9, 2022 at 3:54
  • You're presuming a good explanation, and that it's well targeted, and appear to have an unreasonable faith in the mythical status of help vampires. I write some code-only answers, when someone later adds an explanation, about half the time it helps and I'm grateful, about half the time it's targeted substantially below the competence needed to even ask the question being answered. I need to do better, who doesn't, but I've got it set at least roughly right.
    – jthill
    Commented Oct 9, 2022 at 4:12
  • I see you mostly do C++ questions, where I could easily believe code-only is almost never going to be enough. I do a little C++ here but mostly Git questions, and for that code-only answers where somebody's looking for a poorly-documented option in a complex command or an oddball combo can easily be best. It's a small fraction of the time, but I will stand by my opinion that in rare cases code-only is exactly what the doctor ordered.
    – jthill
    Commented Oct 9, 2022 at 4:17
  • For a c++ example, I don't see any point to adding an explanation to this,
    – jthill
    Commented Oct 9, 2022 at 4:32
  • @jthill I can see plenty of explanations that are useful there. C++ standard changes impacts on the code (inline static), unspecified construcion on order guarantees and gotchas. The OP asked questions which can be addressed with inline descriptions, showing it has demand. Heck, even mentioning some keywords like "crtp" would let people trying to understand the code get it better. Pure code is almost never the easiest thing to understand way to express what code does... Commented Oct 9, 2022 at 16:32
-2

In general, code-only answers should be discouraged. Code, as others have said, is a method of communication. If the code is uncommented, and no explanation is given, if people are only learning what to do but not why you'd want to do it like that, then the response ceases to be educational. Even if it works, we should want to explain our reasoning so people can actually learn and benefit from it instead of having to wonder, "why was this done". As long as edits don't change working code or the author's intent, then I don't care if you edit someone else's post to explain why their code works.

6
  • 2
    I think you maybe missing the question's point, which is whether or not it's OK to edit other people's mostly code-only answers to provide explanations for them. No one is arguing about whether explanations are valuable, but rather whether editing existing answers not your own to provide one is OK. Commented Oct 1, 2022 at 22:09
  • Please delete & flag obsolete comments.
    – philipxy
    Commented Oct 2, 2022 at 10:53
  • 1
    I don't see how the two main points here go together. If we should discourage code-only answers, then letting people get away with that by cleaning up after them via edits seems to send the wrong signal. Commented Oct 2, 2022 at 11:24
  • Yeah that's why I said "in general", as exceptions exist and context matters @MisterMiyagi either way, there's no alternative: we shouldn't ban code only responses or punish them. So I don't think it's bad to be able to edit these responses, so long as no information has been lost. Commented Oct 2, 2022 at 11:54
  • 1
    @MisterMiyagi does cleaning public buildings send the wrong message about tolerating vandalism? Commented Oct 5, 2022 at 1:59
  • 1
    @KarlKnechtel If it leads to praising the vandals for how clean the building is, definitely yes. Commented Oct 5, 2022 at 5:18
-4

"Is it okay?" Sure, as long as you don't change the author's intent which is going to be hard not to do when you are adding so much context and language. It's certainly not the best option.

Instead, write your own answer. Explain the answer and take credit yourself. If you used a code-only answer, link to it and give credit where it is due, but no reason they should get the reputation for your explanation.

4
  • 2
    This advice appears to be about link-only answers, but the question is about code-only answers.
    – Ryan M Mod
    Commented Sep 13, 2022 at 4:26
  • 1
    Re “Explain the answer and take credit yourself.” ... It’s fine to take credit for the explanation, but the code that you copied from another answer should always be attributed to the original author. (I assume you weren’t actually suggesting the passing the code off as your own; “take credit yourself” is easily misinterpreted.) Personally, I credit the original author, frequently upvote their answer that inspired me to write the clarification (unless their code was unnecessarily cryptic/misleading), and then expand with my own narrative. But I try to always give credit.
    – Rob
    Commented Sep 14, 2022 at 18:22
  • @Rob I agree, the second part of that statement says "link to it and give credit where it is due"
    – codewario
    Commented Sep 14, 2022 at 18:41
  • I can see this going out of control with people adding answers with some minor comments and/or explanations that add to an answer posted before (potentially ad infinitum...)
    – PavoDive
    Commented Sep 29, 2022 at 14:41
-5

Provide your own answer with explanation*

Do not edit the answer...but if the user does not respond to a request to update with info, or in the case the user hasn't logged on in years and the reply is now abandoned...I suggest that you reference their post, but also provide a similar answer.

That way you have ownership of a full explanation to the answer. Only do it if it is a direct answer to the OP's question.


Provide a Similar Answer, if:

  • Has the posted answer been fully abandoned and there are no others which satisfy a proper explanation.
  • It is the actual answer needed to satisfy the OP's question.
  • *Do reference the other answer.
  • Provide a full code example based on the other answer.

This response is a clarification to @philipxy marked answer; expanding on

...Post your own answer, giving credit for their code.

3
  • 7
    Just to be clear, if you actually do this, copy the code (with attribution / reference), don't just reference the other post. You definitely want the code+explanation in one answer, such that if / when this better answer eventually gets voted to the top instead of lost in the clutter, it fully answers the question. (In many cases I think it's better to edit the original answer, especially if abandoned, or if you get an OK to do so in comments. Like when an explanation would be small and directly explain some cryptic code. But there are times when copy-with-attribution makes sense.) Commented Feb 21, 2022 at 20:42
  • 6
    But... why? Why not just edit it? Stack Overflow is a wiki. It is collaboratively edited and improved. There is no reason to provide a separate answer saying essentially the same thing.
    – Cody Gray Mod
    Commented Sep 25, 2022 at 9:08
  • @CodyGray Depending on the age of the post and what has been specified, the OPA person may just change it back...for in a sense its their answer. Its happened to me, and I do sometimes edit answers as you are proposing, but I generally put in a comment saying "XXXXX is broken" at minimum.
    – ΩmegaMan
    Commented Sep 26, 2022 at 14:13

You must log in to answer this question.

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