22

I recently suggested a fellow answerer provide some explanation of their code.

IMO an explanation of the code is essential for a full answer… a clear explanation not only educates on the specific details of the code, but can also clarify how to approach about the problem. In addition, rather than mindlessly using some opaque code, it can help users learn small, digestible, relevant parts of the solution for future use. I mostly learnt how to code this way.

However, this was roundly rejected by the answerer.

IMO an explanation of basic code is far less useful than a glance at the man pages for anyone who doesn't understand it

I almost always explain my code in detail, for example here.

I personally think explanations are essential, and I tend to only upvote answers with explanations (unless the code is very simple). The site help isn't clear on this point. In the comments, another user (cas) also supported the idea of including explanations. However, the (rather aggressive) answerer has >100k on SO, which made me doubt my opinion.

Am I wasting my time writing detailed explanations? I see both strategies employed on U/L, and both receive upvotes. Is there a consensus on U/L or SE on whether explanations are essential, or even important?

21
  • 16
    Manuals describe tools, they do not generally describe how to use them. Explaining how the code uses the tools is a good thing, especially when making assumptions and when there may be conditions under which the code may fail.
    – Kusalananda Mod
    Aug 1, 2019 at 7:16
  • 3
    @Sparhawk - sorry if I came one a bit strong in my response to your comment. I'm just utterly sick of posting trivial answers like awk '{print $1+1}' and that causing the "possibly low quality" tool to flag it as such for being code only and then some queue-jockey (not you) with no idea about the domain coming along and saying "your answer could be greatly improved if you comment it..." and then it initially getting downvotes from the other queue-jockeys. Meanwhile someone else writes an answer that's war-and-peace but complete nonsense and it doesn't get any negative responses.
    – Ed Morton
    Aug 2, 2019 at 6:11
  • 3
    @EdMorton It did come across fairly aggressively (especially to cas), but that's okay. Also, I think it's a straw-man argument to suggest that the code from your answer is of similar complexity to the example here. I understand your argument, but this comparison does not support it IMO. Regardless, from your other comments, I realise that you feel your perspective is correct, so your point is made.
    – Sparhawk
    Aug 3, 2019 at 0:51
  • 3
    @EdMorton I don't downvote answers without explanations, but i'm not likely to upvote them either. and if i think it's a reasonable or good answer that could be greatly improved with an explanation, I'll sometimes leave a comment saying that.
    – cas
    Aug 4, 2019 at 0:55
  • 4
    To me, the most important point of SE sites is to teach, to pass on knowledge and understanding (to enable people to figure out their next problem themselves), not to just give magic answers. Explanations work towards that, answers without explanations undermine it and encourage a cargo-culting copy-and-paste-without-understanding use of answers.
    – cas
    Aug 4, 2019 at 0:56
  • 1
    @cas I completely understand your opinion and completely and utterly disagree that the approach you advocate is the best way for people who want to learn to learn from basic scripts for the reasons I've already stated. After 40+ years programming including around 15 years teaching SW engineering I think I have a pretty good handle on it. As you'll see from stackoverflow.com/a/45420607/1745001 and many of my other answers, I do explain answers when necessary, it's just not always necessary. Everyone is welcome to upvote/downvote, accept or not as they see fit. Let's move on.
    – Ed Morton
    Aug 4, 2019 at 3:45
  • 3
    @EdMorton, you really should post your viewpoint as an answer here so that others can show their agreement on it.
    – ilkkachu
    Aug 5, 2019 at 7:30
  • 2
    @EdMorton, well, if you don't want to even offer an alternative to be voted on, and are "utterly sick" and "feeling frustrated and annoyed", then I think it might not be a bad idea to take a break.
    – ilkkachu
    Aug 5, 2019 at 15:43
  • 3
    @EdMorton, well, you also removed the explanation I added to your answer linked to from this question. The addition of that explanation cost you nothing, but on the other hand, removing it must have taken at least some seconds. Since you took the trouble of removing it, I can only agree that you seem to care very little about others. (The potential readers of that question, that is, the ones who might wonder e.g. what the & does in the second argument to gsub. And don't say it's easy to look up, special characters are notoriously hideous to search for in manuals.)
    – ilkkachu
    Aug 5, 2019 at 18:44
  • 1
    @EdMorton, but since you do seem to care enough to comment on this, might I suggest using tab-completion on the usernames? Hitting @, i and tab should make it much easier to enter my nick correctly, and entering it correctly would have the advantage that it would actually ping me, which is pretty much the main point of using @ + username
    – ilkkachu
    Aug 5, 2019 at 18:47
  • 1
    @ilkkachu As I believe I have said repeatedly - I don't add explanations to trivial code because I believe it is better for the reader to not have those explanations. You added an explanation that I did not want to be present in my answer and so I removed it from my answer. If I thought such an explanation would make it a better answer then I would have provided it myself. Thanks for the @i tab suggestion, I hadn't heard of that before and it is useful. wrt I can only agree that you seem to care very little about others - as you know, that's not what I said. I won't be responding further.
    – Ed Morton
    Aug 5, 2019 at 19:27
  • 1
    @ilkkachu 1.This is a public place, not your private playground; you don't tell people to "take a break" if they don't like it. This also applies to other petulant regulars and mods (you know who you are). 2. the nick completion doesn't work in the mobile version of this site.
    – user313992
    Aug 5, 2019 at 20:09
  • 2
    @UncleBilly, I didn't order them to take a break, I only suggested that it might be better to take a break than to continue something that one only causes frustration. As far as I know, people contribute on stackexchange because they want to, not because they have to. As a hobby, or something like that. And hobbies that cause frustration aren't very good hobbies. Now, I did honestly attempt to phrase it so that it wouldn't come out too bluntly, and I'm sorry to see that I failed.
    – ilkkachu
    Aug 5, 2019 at 20:24
  • 2
    @UncleBilly, As for tab completion, I suspected it might not work in all environments, but the point still stands: the ping system works better if people's nicks are written correctly, and actually bothering to write people's names correctly seems like the respectful thing to do.
    – ilkkachu
    Aug 5, 2019 at 20:27
  • 1
    Obviously, there is no consensus, just a very strong majority. But that will not convince people who "know better than all the others". I myself appreciate people giving good explanations and even more people adding explanations to other people's answers -- especially to mine, if it was not good enough.
    – Philippos
    Aug 31, 2019 at 17:53

3 Answers 3

Reset to default
29

Answers here are not just for the OP, but for future visitors who come here with similar problems. Of course, for an answer to be useful to such visitors, for them to adapt it to their purposes, they should be able to understand it. That means providing some explanation of any code. Maybe not a full description of the syntax, but at least an explanation of the key parts of it, and how the code achieves those key parts. Even the OP might have to adapt the code, if their example input is structured differently from their actual input.

IMO an explanation of basic code is far less useful than a glance at the man pages for anyone who doesn't understand it

Why even write any code then? Just put RTFM in the answer. Oh wait, that's not allowed. What's "basic" to one isn't necessarily basic to others. Even something as trivial as:

awk 1 ./*.txt

needs explanation.

18
  • Thanks @muru. In reference to your example, I noticed that you didn't actually post an explanation until the comment. To be fair, AFAICT the answerer from my question also does that. This actually seems counter to my instinct, and the first part of your response.
    – Sparhawk
    Aug 1, 2019 at 3:52
  • 9
    @Sparhawk Exactly! I didn't add an explanation because I thought it was trivial. Turns out, at least one user didn't understand it, and needed explanation.
    – muru
    Aug 1, 2019 at 4:57
  • 5
    Quite. awk 1 doesn't make sense until you realise that missing conditions and actions have inferred default values.
    – Chris Davies
    Aug 1, 2019 at 7:43
  • 1
    wrt Why even write any code then? so the person looking for help gets the help they immediately need and has something they can look up in the man pages and google. Just responding RTFM doesn't tell them what it is they need to look up in the manual. i++ doesn't need a comment and neither does any other code that can be figured out by spending a few minutes looking at the documentation plus just posting that basic code leaves the answer uncluttered for people with experience and teaches those without experience where to go to learn about the current code and more.
    – Ed Morton
    Aug 2, 2019 at 5:32
  • 9
    @EdMorton we're not here just for the fulfilling the immediate needs of the asker, though. The goal of the site is long-term, and to be reasonably self-contained. If for any answer I absolutely have to go to an external resource to understand it, then that answer has failed. It's no better than a link-only answer.
    – muru
    Aug 2, 2019 at 5:35
  • @muru - I didn't say we were, yes it is, and that's not the kind of answer we're talking about.
    – Ed Morton
    Aug 2, 2019 at 5:38
  • 3
    As for i++, Python, for example, has no i++. If the person had never studied a language with an increment operator, they would have no idea what a ++ is.
    – muru
    Aug 2, 2019 at 5:38
  • So we should document i++ every time we write it in the thousands of answers that use it for the sake of the 1 in 100,000 people who have never seen it before and can't figure out what it means? That's the kind of absurdity I'm claiming we should not cater to. Post simple code and let people look up parts and/or ask questions if they have to - anything else is a waste of time for the people providing answers and the vast majority of people reading them in future who already have a basic understanding of the domain and is far more effective at teaching everyone else how to learn the topic.
    – Ed Morton
    Aug 2, 2019 at 5:44
  • 1
    @EdMorton of course not. But we should explain what the goal is. For example, in unix.stackexchange.com/a/522083/70524, I didn't explain what ++ is, but I did say what I was doing with it there. Because what exactly ++ did was only incidental to what I wanted as the outcome. Yet the syntax can be obscure enough that it's worth explaining what the goal is, so someone looking to adapt it can do so to whatever extent they understand the syntax.
    – muru
    Aug 2, 2019 at 5:48
  • 1
    I think all of your comments in that code are completely redundant as it's extremely obvious what the code is doing but lets just agree to disagree. The ++s in that code are doing nothing except using up cpu and memory, though, you could just remove them. Also the index to ks should be constructed using $1,$2 instead of $1 $2 since a bc and ab c both concatenate to abc - you need to provide a separator to create unique keys from 2 values. That's probably why the OP commented that some of the data went missing.
    – Ed Morton
    Aug 2, 2019 at 5:56
  • 1
    I'm just going to continue to assume some degree of intelligence and capability from the people we're trying to help, not re-document the things I think are easy to figure out after a glance at the existing documentation, and reply to questions when asked.
    – Ed Morton
    Aug 2, 2019 at 6:15
  • 8
    The comments in muru's awk script for that 3-column csv question are precisely the sort of thing that the OP (or some future visitor) might need to make the leap from a terse man page list of functions to being able to writing a script to achieve a goal. It's a documented example of the kind of algorithmic thinking needed to use variables and functions and other language syntax elements to solve a problem.
    – cas
    Aug 4, 2019 at 1:08
  • 4
    Also remember that many users here are not programmers, they're people with data they need to process - academics with genetic data files, users with accounting records or album collection catalogues or whatever. They may never learn enough to be "real programmers", but they can learn how to think enough like a programmer to solve their current problem, and maybe some of their future problems....or, at least, enough to write a good question next time.
    – cas
    Aug 4, 2019 at 1:14
  • 9
    sometimes all it takes is one well-explained answer to trigger a new level of understanding: "aha! so THAT's how that works - I always wondered what that did".
    – cas
    Aug 4, 2019 at 1:15
  • 1
    @bu5hman I write my answers not only for the OP, but also for anyone else who reads my answer. If the OP thinks "so what?" or worse, I don't care - the "price" of them getting an answer is that they may get some explanations spelling out the bleeding obvious. And i write comments (in code and text) that address common obstacles to understanding (e.g. i'll usually put a comment in perl code that uses arrays mentioning that, unlike awk, perl arrays start from zero)
    – cas
    Oct 17, 2019 at 0:53
5

(I think this is my first post on meta, please excuse me while I proudly step on other people's toes.)

Am I wasting my time writing detailed explanations?

I'd like to say no, since explanations are obviously a good thing in general and I like to believe that I usually explain things in great detail as well... but I also understand the other side, that sometimes, maybe it's just too much.

Allow me to elaborate a little.

When I see shrubbery like "\"" or spaceship like /,",\, then yes, it takes me a bit to parse that, despite knowing what $, /, & mean. The lack of syntax highlighting doesn't help much either, it's all a single shell string in the end — someone please come up with a way to highlight such encapsulated codes anyway.

So yes, this may be a little difficult to understand at a glance. Some explanation would probably be nice. But is it mandatory? And which level of detail would be appropriate?

How deep down the rabbit hole do you go when trying to explain every little thing? Do you have to explain that . matches any character every single time you do anything remotely related to regular expressions? I think that might be what Ed Morton was referring to with the $1+1 example. If you even explain that $1 is the first field, you might just be overdoing it a little. By the way, you forgot to explain why the , had to be added back - of course, it's because the -F, ate it. Although it's great to explain such things down to the smallest detail, just where does it end?

For an explanation, the general idea should be enough (and too much detail might even distract from it). Quote the first argument ($1="\""$1"\""), quote each letter of the second argument (gsub(/./,",\"&\"",$2)). End of story. No need to be long-winded and probably no one cares about how exactly it does that anyway (and they could research, or ask a dedicated question about it, where rabbit-hole level of detail is expected).

All answers here are given for free and you can't force other people to change their style to yours. I see the answer got downvoted already and I think it's a bit unfair.

Given a choice between a good answer with no explanation whatsoever, and no good answer at all, I'll take the good answer and thank you very much. Demonstrating input and output is already very good, and is also part of documentation - some of the others didn't even do that. Additional explanation would be the cherry on top, sure, but in the context of this question it's not mandatory.

If people started adding things to my answers (in a way that does not agree with my own style, and the way I explain and demonstrate things), I might feel inclined to remove it as well and feel in my rights to do so. You can always post your own answer, after all.

7
  • Oh boy, I messed up. The answer wasn't edited by you at all... >_<
    – frostschutz
    Aug 12, 2019 at 19:52
  • 1
    Thank you for the post. "All answers here are given for free and you can't force other people to change their style to yours." Of course! That's why I wanted to start an open dialogue.
    – Sparhawk
    Aug 13, 2019 at 1:27
  • 6
    Please note that if others add things that are relevant and helpful to your post, and you insist on removing that, the mods will come to the defense of the editor. The objective here is to build a useful resource. If someone doesn't want their style to be changed, they should get a blog. Adding an explanation is a wonderful, helpful edit.
    – terdon Mod
    Aug 14, 2019 at 13:06
  • Relevant and helpful is subject to opinion. Hence the entire voting system all around. Useful. Not useful. Or for questions: shows research effort, or not. If we expect questions to have research effort, why should answers have to spoon-feed down to the tiniest details? Is it helpful or overdoing and distracting? It's optional and up to the author to decide. Most answers assume prior knowledge in some way and they're plenty useful all the same. Not including the unasked-for beginner tutorial is a high level complaint, and there's better tutorials out there.
    – frostschutz
    Aug 16, 2019 at 13:11
  • 1
    Don't like it? Leave! Get a blog. Strong argument and somewhat disrespectful to those who make every effort to write correct/quality answers. Why not wiki? In a wiki there is one answer, everyone edits it together until it's just right, no votes, no nonsense points, no author shown (unless you dig the edit history). If someone wants to edit other people's answers, they should get a wiki. This is not a blog. But it's also not a wiki. It's its own thing, and answers have authors, and you can post your own. I rarely get edits and doubt others would enjoy if I started mass editing theirs.
    – frostschutz
    Aug 16, 2019 at 13:15
  • ...edits as in those that come close to changing the nature of the answer (like adding so much text that half of it is yours). I'm naturally happy with edits that fix spelling, grammar, formatting, syntax errors, broken links, etc. but if you feel that an answer should've been written in a different fashion, I feel that at some point it should be posted as your own answer. I had one answer where someone thought it should be a shell script instead, and I'm glad they posted it as their own, and not attempt to edit mine.
    – frostschutz
    Aug 16, 2019 at 13:31
  • 3
    "spaceship like /,",\ " made me spit tea over my keyboard. Thank you for that one! But about that my-answer-belongs-to-me thing: Honestly, persons like Ed, who seem to be convinced that their opinion is worth more than the combined opinion of the community, may feel better at a platform that fits their mindset. Anyhow, besides your promotion for edit wars to defend the integrity of one's answers, you get an upvote, at least fr the space ship.
    – Philippos
    Aug 31, 2019 at 17:44
-4

Contributors who found a working solution in code do make a valueable effort which will help others. If you think that is not good enough, why not throw in a few extra hours and improve the post yourselves? The original contributor already gave you most of what you need! Do not suppress their posts! That kind of antagonism will make the site utterly unpopular, and people have quite enough antagonism at the workplace already, let me tell you.

2
  • 4
    1) I was not given anything of "what [I] need". The question was not mine. (2) I could have edited the post, although some answerers are a bit defensive about this. However, these edits would still be predicated on whether there is a consensus… which is the point of this meta-question. (3) I did not suppress the answer. I didn't flag it for deletion, nor would that be deserved. Nor did I downvote (although five others did). (4) The comment thread is deleted, but I made a mild suggestion to clarify, supported by cas, and the answerer responded aggressively. I have not been unduly antagonistic.
    – Sparhawk
    Dec 10, 2019 at 2:27
  • @dotbit "why not throw in a few extra hours and improve the post yourselves?" That's the problem: Somebody did improve it by adding an explanation, but the author of the answer reverted it, suppressing the post.
    – Philippos
    Mar 28, 2022 at 9:05

You must log in to answer this question.

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