Timeline for Is domain-knowledge required to determine whether code snippets should be commented?
Current License: CC BY-SA 4.0
33 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Jul 5, 2019 at 10:03 | comment | added | collapsar | @weegee For beginners to better understand a tool or technology, they have to consult the docs. There is no way to avoid this effort. There are legitimate reasons to use without knowing but imho this site does not need to cater for them. In this case, after all, it is not a verbose script that might require guidance by some expert on concepts, tacit assumptions, conventions or 'tool philosophy' to get a grasp of. Giving such hints in the answer would not improve it - it would provide context for users who still could not employ the answer for their own task as-is. | |
Jul 5, 2019 at 9:52 | comment | added | collapsar | Comments' usefulness depends on the reader's use case. Folks with no/feeble domain knowledge hunting for code to tackle a one-time job do benefit from a note like 'regex search/replace on the the third verb in a line, printing the result` while this level of detail is next to offensive for regular awk users. @EdMorton True, the former would benefit more from consulting the docs in order to understand but few will do that for lack of time or a 'reward-w/o-effort' mindset. However, it is an absolute no-go to massively downvote a correct answer for the lack of what has no impact in correctness. | |
Jul 5, 2019 at 7:04 | history | edited | Himanshu |
edited tags
|
|
Jul 4, 2019 at 5:39 | comment | added | Ed Morton | and this whole debate is absolutely ridiculous anyway since the tool only flags tiny code snippets which we can debate whether they need explanation or not and meanwhile does not flag large scripts with no or hopelessly inadequate explanation that almost always should have some. | |
Jul 4, 2019 at 5:35 | comment | added | Ed Morton | @MatthiasFripp you're making my point. Anyone who didn't understand the awk script at a glance (and to be honest I'm struggling to accept you couldn't figure out that $3 was the 3rd field but lets take that at face value) and wanted to could have figured it out by glancing over the first page or 2 of the awk manual and by doing so would have learned a LOT more about awk than any explanation I would have added. For the sed regexp, again - it's literally a Basic Regular Expression and anyone who doesn't know those really needs to look at the POSIX spec or find out otherwise. | |
Jul 4, 2019 at 5:30 | comment | added | Ed Morton | @thirtydot understood and thanks for the advice but I'm not going to change my ways to accommodate a bunch of people who think they're making a useful contribution by rubber-stamping a tools output. Right now I couldn't care less if they downvote my answers and if I ever do care then I'll just stop answering. Obviously my answers get vastly more upvotes than downvotes and I answer questions to try to help people but I'd be fine with not doing that too, it's not a big deal either way. | |
Jul 4, 2019 at 3:22 | comment | added | Matthias Fripp |
@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.
|
|
Jul 4, 2019 at 0:23 | comment | added | thirtydot | @EdMorton: Something like this happened to me recently too. If your answer ends up in the "low quality posts" queue, you're all but guaranteed to get downvotes and if you're lucky, patronising comments. Your answer can end up getting deleted too. You must dodge the LQP criteria, or else you get wonderful experiences like this one. A single line of text explanation (or useless filler) would have probably been enough in this case. In fairness, a lot of the stuff in the LQP queue is garbage. | |
Jul 3, 2019 at 22:32 | comment | added | Martin Zeitler |
recently I've answered i-- but it was too short for a code-only answer.
|
|
Jul 3, 2019 at 21:46 | comment | added | Ed Morton | 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. | |
Jul 3, 2019 at 16:02 | comment | added | S.S. Anne | 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. | |
Jul 3, 2019 at 15:30 | comment | added | Ed Morton |
Yeah I was just looking at that. Thanks to this post here we now have a bunch of people who agree with @Eric's original stance hopping over and downvoting what is actually the simplest, clearest, most robust answer and effectively hiding it from future readers. How very useful. smh... And no I definitely won't start adding increment i comments to my answers.
|
|
Jul 3, 2019 at 15:30 | comment | added | Eric Hauenstein | @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. | |
Jul 3, 2019 at 15:27 | comment | added | Erik A | 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. | |
Jul 3, 2019 at 15:21 | vote | accept | Eric Hauenstein | ||
Jul 3, 2019 at 16:02 | |||||
Jul 3, 2019 at 15:20 | comment | added | Ed Morton | @BDL Really? It took me a couple of minutes to figure out if the accepted answer would work or not since it's relying on a default action of printing the current record that's only executed it the action specified in the conditional context evaluates to non-zero and non-null. THAT is the truly tricky, non-obvious part of the accepted answer and it has no explanation given and yet no-one is complaining about or flagging that while we're having a debate over the lack of comments on a completely obvious, trivial statement. | |
Jul 3, 2019 at 15:17 | comment | added | Ed Morton |
@ErikA the accepted answer can benefit from explanation as it's using constructs unique to awk and bash (setting -F , use of $0, use of a here-string, etc.) in a non-obvious way. My answer does nothing non-obvious.
|
|
Jul 3, 2019 at 15:15 | comment | added | Ed Morton | @weegee again, the sweeping "all answers need comments" statement. I disagree. Good luck to you. | |
Jul 3, 2019 at 15:13 | comment | added | BDL | @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. | |
Jul 3, 2019 at 15:12 | comment | added | weegee | 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 | |
Jul 3, 2019 at 15:10 | comment | added | Ed Morton | @weegee the regexp in the sed script is literally a Basic Regular Expressions as defined by POSIX. Again, easy to look up and far more useful than me explaining them for the very few people who might need to do so. | |
Jul 3, 2019 at 15:10 | comment | added | Erik A | @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. | |
Jul 3, 2019 at 15:09 | comment | added | Ed Morton |
@BDL the key word is usually, not always. The question in this case is how to change a b c,d e to c.d and I posted awk '{sub(/,/,".",$3); print $3}' . I contend that almost everyone reading that could figure out what it does even if they'd never heard of awk before and if you can't then a quick google would be far more useful than me saying "replace . with . in the 3rd field then print that 3rd field".
|
|
Jul 3, 2019 at 15:08 | comment | added | weegee | @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. | |
Jul 3, 2019 at 15:05 | comment | added | BDL |
@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).
|
|
Jul 3, 2019 at 15:03 | comment | added | Ed Morton |
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 .
|
|
Jul 3, 2019 at 15:00 | comment | added | weegee | @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 | |
Jul 3, 2019 at 15:00 | answer | added | Servy | timeline score: 20 | |
Jul 3, 2019 at 14:57 | comment | added | Erik A | 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. | |
Jul 3, 2019 at 14:56 | comment | added | BDL | 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. | |
Jul 3, 2019 at 14:54 | comment | added | weegee | 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 | |
Jul 3, 2019 at 14:53 | history | edited | E_net4 | CC BY-SA 4.0 |
deleted 29 characters in body
|
Jul 3, 2019 at 14:45 | history | asked | Eric Hauenstein | CC BY-SA 4.0 |