28

This answer came up during a VLQ review, and I'm involved in a mild disagreement as to whether the answer as posted would be improved with comments.

Would it be better to leave code-only snippets to people with domain knowledge to determine whether comments are necessary?

28
  • 22
    No, it won't be better. We cannot assume that only expert people will see that answer. Beginners too will see it and it the answer should also explain how it works so the beginners can better understand it
    – weegee
    Commented Jul 3, 2019 at 14:54
  • 28
    A bunch of code without explanation is (almost) never a good answer. Especially when you skim through several answers, highlighting what the code does and how it solves the problem is always of advantage.
    – BDL
    Commented Jul 3, 2019 at 14:56
  • 3
    I agree. A tiny clue about the syntax of a language helps so you can recognize truly self-explanatory code, but preferably even novices should be able to understand an answer. In a way, not being an expert is preferable because I often encounter situations where I think something is self-explanatory but it still confuses the OP.
    – Erik A
    Commented Jul 3, 2019 at 14:57
  • 2
    @ErikA be it that the OP is a gold badge in the field. I always add my answers with an explanation or inside comments in the code itself. Because the answer will be exposed to other people who have arbitrary knowledge in the field. Also, the code only answers don't look good. I tend to ignore them mostly
    – weegee
    Commented Jul 3, 2019 at 15:00
  • 4
    There is code which does not need to be commented. When you write i++ do you add a comment saying incrementing i. Hopefully not. So saying with a sweeping gesture that "commenting code is better than not commenting code" is absurd. If such a thing were true then the tool that flags code-only answers as possibly low quality could make that determination itself. People who understand domain basics don't want the basics re-explained every time they read an answer and people who don't will benefit far more from a glance at the existing documentation than being spoon fed incrementing i.
    – Ed Morton
    Commented Jul 3, 2019 at 15:03
  • 11
    @EdMorton: Noone said you should comment every single statement you write. But at least some high-level comment on why the code solves the problem is usually beneficial. (And if your answer consists only of i++, then I doubt the question was a good one).
    – BDL
    Commented Jul 3, 2019 at 15:05
  • 5
    @EdMorton here your answer seems to contain some regular expressions and you can very well explain them like the user who's answer is accepted.
    – weegee
    Commented Jul 3, 2019 at 15:08
  • 2
    @EdM While the code is relatively trivial, the accepted answer isn't that complicated either and OP did ask for clarification there even though it already had a short comment. My assessment here is that he would likely either ignore or just copy-paste and use the answer. Educational styles differ, and having someone look up and work out what you did would be ideal, but that'd likely not happen in this case imo.
    – Erik A
    Commented Jul 3, 2019 at 15:10
  • 4
    If that's the case then every answer should just paste code and people should copy them. Then stack will become a library of codes where people come, copy the code and paste them instead of a wiki which it is first. @EdMorton
    – weegee
    Commented Jul 3, 2019 at 15:12
  • 4
    @EdMorton Even as someone who knows regular expressions, it takes me some time to figure out what exactly your code does. Just to determine if the answer is relevant or answers the question takes more than just one look. In the accepted answer, I can tell in seconds if this is what I need.
    – BDL
    Commented Jul 3, 2019 at 15:13
  • 4
    One thing that does bother me here is voting on the answer. While I may think it'd benefit from an explanation (even only to avoid an auto-flag and not waste the time of reviewers), the code is solid and simple, and doesn't meet the not useful tooltip that goes with a downvote imo.
    – Erik A
    Commented Jul 3, 2019 at 15:27
  • 1
    @ErikA I never vote on code-only answers, unless they are obviously wrong, which I am not qualified to judge in this case. I suspect the downvotes are from the Meta-effect, as all three answers were zero when I posted. Commented Jul 3, 2019 at 15:30
  • 2
    In fact, a few questions that I've asked have gotten answers like this (from this user, even) with no explanation. I, however, asked for an explanation, and received one. The answers didn't really make any sense before the edits adding the explanation.
    – S.S. Anne
    Commented Jul 3, 2019 at 16:02
  • 1
    Right. With any answer there's the possibility that the person who posted it thought they had provided enough information but after reading it, the man pages, googling, etc. someone needs a bit more help and so asks a question and gets an answer. It's just this "all code must be commented" mindset that's a problem as it discourages people from providing answers. It if continues all we'll be left with is the queue-jockeys trying to impose their uninformed will on the rest of us while the those of us actually helping people give up answering since it becomes too much effort to answer questions.
    – Ed Morton
    Commented Jul 3, 2019 at 21:46
  • 4
    @EdMorton I have some experience with regexes, but I didn't know that awk uses $3 to identify the third field. Your awk answer was unintelligible to me until I read your comment here: "replace , with . in the 3rd field then print that 3rd field". The OP may have puzzled that out of man awk, but your clarification would have given them the right information in the right place at the right time. I would need to do a lot more research to figure out how your sed answer works. Regexes are nearly write-only, so a little explanation of the approach you're taking goes a long way. Commented Jul 4, 2019 at 3:22

1 Answer 1

20

I'm involved in a mild disagreement as to whether the answer as posted would be improved with comments.

That has nothing at all to do with the LQP queue. Whether or not an answer would be improved with a more detailed explanation has nothing to do with whether or not the answer is an answer, just whether or not you think it's a useful answer (which is not what that review queue is there for).

You're welcome to use your up and down votes (and comments) to indicate how useful you think the post is, although you should be careful when voting on posts in areas you aren't familiar with. I won't say you can't determine if a post is useful or not without domain knowledge, because there are cases where it's clear even without domain knowledge, but you need to be careful when doing so, as it's very easy to mislead others by voting on a post when you do not in fact know how useful it really is to people who are actually faced with the problem in question.

8
  • So, if I read this correctly, commenting without voting is the course you recommend? Commented Jul 3, 2019 at 15:14
  • 4
    @EricHauenstein From the queue? No. As a reviewer in the queue, you should do nothing, the post merits no action. Outside of the queue, you should not vote unless you're confident in the usefulness of the post, and you should not comment on how it can be improved unless you're confident you understand a problem with the answer and how to improve it. If you're very confident of those things without being familiar with the subject in question (usually as a result of the problem being very significant), so be it, if not, then leave it to those who are.
    – Servy
    Commented Jul 3, 2019 at 15:16
  • Okay, apparently I stand corrected. Future code-only answers in the queue will be punted. Commented Jul 3, 2019 at 15:23
  • 4
    @EricHauenstein: There are different opinions if you may leave comments on code-only answers in the review queue. Low quality posts and code only answers suggests to leave such comments.
    – BDL
    Commented Jul 3, 2019 at 15:44
  • 1
    If we truly want to follow the position of no commenting from LQP, we might want to discuss that even more publicly, and address the automated comments LQP leaves. I've always been under the impression that commenting is recommended, even though I rarely comment, but I do see a lot of comments from people coming from the queue.
    – Erik A
    Commented Jul 3, 2019 at 15:53
  • 6
    @ErikA It's not like you're not allowed to comment, moreso that the purpose of the queue is there to judge whether or not the post needs to be deleted, not to comment on how acceptable but improvable posts can be improved (there are other queues that do exist to do that). Even if you're technically commenting in the review queue's UI, you're not doing it as a part of the review.
    – Servy
    Commented Jul 3, 2019 at 15:58
  • 3
    @EricHauenstein, there's a difference between a code snippet without (code) comments and a code-only answer. An answer without any explanatory remarks can almost always be improved. It might or might not make sense for some of those remarks to be made in the form of code comments. Commented Jul 3, 2019 at 22:36
  • 1
    Dunno you, but there's an edit button on the queue. How about improving these posts?
    – Braiam
    Commented Jul 5, 2019 at 7:32

You must log in to answer this question.

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