12

Does this site have any sort of canonical policy regarding command/code edits?

Or, more exactly, when proposing an edit to code or a command (or just directly editing it as per 2k privileges), where do we draw the line for editing code? Basic typos? Major revisions?

4 Answers 4

12

TL;DR

I don't think there is a detailed site policy and I don't want there to be one, because it would be too complex to codify*. No policy, however sensitively and scrupulously defined and flexibly applied, can replace learning through experience. I much prefer the SE way of respecting experienced users and having an initial learning process (suggesting edits which are checked by the community) and checks and balances in place.


Anyway, FWIW, here is my take (I guess I am a pretty prolific editor) in more detail, subjective as it must remain.

There is a rather generic list of guidelines that pops up at the side of the screen when, as an unprivileged user, you set out to suggest an edit. I can't remember what that looks like on Ask Ubuntu but I'm going to assume it's similar to what I see on U&L and Stack Overflow:

How to Edit

► fix grammatical or spelling errors

► clarify meaning without changing it

► correct minor mistakes

► add related resources or links

always respect the original author

There's no special mention of code here, so we can assume that the same guidelines apply to code: I should correct minor mistakes. There is no mention of formatting, which is probably in need of editing more often than anything else, but I assume you mean the actual code text, not the formatting.

I believe that "minor mistakes" is deliberately vague: as editors we are trusted to know when the mistake can be salvaged by editing, and when we should do something else instead. I don't mean that we are or should be expected to always know that, I mean, that if you set out to edit a post, you should have the knowledge gained from observation and experience to do so appropriately. (As mentioned by @edwinksl, In the context of review - if you are unsure, the skip button is your friend)

I err on the side of editing. My bottom line is, if I can improve the site by editing, I should do so. Edits can always be rolled back or re-edits done. In practice "improving the site by editing" is a complex goal and there are multiple factors to consider (*this is why I think no policy could be codified) - in particular I always first ask myself:

  • Is the post author experienced and active on the site?
    • If so, I will usually comment rather than editing unless there is some obvious typo or slip-up
    • If not, I will usually go ahead and edit, with a couple of exceptions*

If I go ahead and edit, here's what I do in situations where code is involved, not including formatting:

  • If the poster has not included commands that I think should have been included, I include them (as a fairly extreme example, if a post says "pass intel_idle.max_cstate=1 as a boot parameter" I will generally edit into it an explanation of how to set boot parameters with commands. Less drastically, if a post mentions installing a package, I will often edit in the command to install the package).
  • If there is something in the code that I am fairly sure is an error, I will correct it.
  • I usually switch out any backticks used for command substitution and replace with $() because of the potential of the former to cause markdown-mixups
  • If someone has written something similar to what I would write as an answer myself, and I can think of an additional related command suggestion, I will usually edit it into the answer rather than writing an answer of my own.
  • If the code makes what I consider a bad minor decision (typically sudo gedit (or sudo <any graphical application>) I will "fix" it (sudo -H gedit and so on)

*situations when I don't usually edit:

  • If the code makes what I consider a bad major (ie the answer will need to take a significantly different approach to avoid it) decision or fails in a way I can't fix (when I test it), I will usually leave a comment (and downvote if warranted) instead of editing.
  • If I think the code could be simplified or improved, I will usually comment instead of editing.

I should say that I always eventually check back on my comments. If a post still seems bad after I've given time for it to be fixed by the poster after leaving a comment, I will either (preferably) edit it or, if not done already, downvote it. Occasionally, I leave a comment for the sake of future visitors in cases where I have no intention of editing the post, but in general I will edit unless there is a compelling reason not to (generally that the post is an established one and the author is active).

Context sometimes matters - what else is going on besides the code in this post? Is it one of numerous answers to a question? Is that question ambiguously phrased, with answers addressing different possible sides of it? Respecting the original poster might be quite a wide ranging consideration - I try to look around to see if I am treading on any other toes too when editing (for example, if I "clarify" a question, am I making one of the answers lose meaning and usefulness? How can I avoid that?)

3
  • 1
    I am pretty sure this describes a balanced, cautious and conscientious editing policy, which is the best possible for the site's quality. Jan 18, 2017 at 9:43
  • @JacobVlijm thanks a lot! :D
    – Zanna Mod
    Jan 18, 2017 at 9:44
  • 1
    @Zanna Perhaps you want to introduce the extremely useful "Skip" button for editors who come across reasonable-looking code/command edits but lack the necessary knowledge/expertise to determine if the edits are technically sound.
    – edwinksl
    Jan 18, 2017 at 14:12
4

Yes, there is a site policy on this. Here, just like on all other sites of the Stack Exchange network, the policy is that edits are good, edits are nice, editing often keeps your head free of lice1.

The SE sites are collaborative efforts. They sit at the cross-section of blogs, forums, wikis and sites like Digg/Reddit:

venn diagram of forums, wikis, blogs and digg/redit

Editing is an integral part of what we do here. All content on the site is freely editable and everything posted here is posted under the CC by SA license. This means that as soon as you hit the submit button, your post is no longer your private domain but is available to everyone and everyone has the right to modify it.

This is a Good Thing®. This is what lets us shine and what sets us apart from traditional forums. Sure, I could write a nice little script that answers your question. However, if that is later edited by 10 people and improved, it can become something much better than what I could have written myself. So yay! A better answer! That's good for the site and it's good for whoever asked the question.

There's nothing special about code. If you see code that can be improved, do so! Just like if you see a post that can be improved by removing fluff, or improving grammar or whatever. If the OP really objects to your edit, they can always roll it back. And yes, if you're not 100% sure that your edit would be an improvement, then of course, don't edit! If, however, you know you're improving the answer, then there's absolutely no reason not to edit.

I tend to be most active on the various command line/text processing tags. That's what I know best and that's the domain where I feel confident that the changes I make are improvements. So yes, if I see an answer that is giving a poor solution and I see an easy way to improve it, I will do so. My other choice would be to downvote and leave a comment. Why would I choose to do that, if I can see a simple fix? Far better to fix it and upvote instead!

So no, there's nothing special about code. It's just an answer and answers are—and should be—editable.


1I may have paraphrased, slightly.

15
  • 2
    With one important qualification - the core nature of the answer mustn't be changed. I once rolled back an edit to an accepted answer which replaced it entirely with another answer to the same question!
    – muru
    Jan 18, 2017 at 9:24
  • I don't think it's a secret that I feel more attached to what I write than some others :). That isn't my argument here however. Although in theory there is no difference in editing text or code, in practice there is. Like I mentioned before, I've had edits by excellent users, with a (much) bigger over all knowledge than I, make edits to my code which turned it into a non-working solution. I am sure they knew what they did, but simply made a mistake. People do. You do, I do. That's why I plea for a higher threshold to edit code than for editing out textual explanation or grammar. Jan 18, 2017 at 9:30
  • I don't think this is in any way at variance with the policy of the SE network. ^ Jan 18, 2017 at 9:31
  • @JacobVlijm yes, that's why edits can be rolled back. That is not, however, any reason to stop editing. Obviously, bad edits can happen and those should be corrected. Nobody said the opposite.
    – terdon
    Jan 18, 2017 at 9:54
  • Sure, but my point is, driving a 40 ton truck in the center of Amsterdam requires more responsibility then riding a bike in the forest. In other words; the threshold to edit code should be higher then correcting a grammar error., unless you know code can be harmful. Jan 18, 2017 at 10:01
  • @JacobVlijm improvements are always good. Whether they improve code or prose is completely irrelevant. I get that you object to this (you have very often made that clear in the past) and that's fine, you're entitled to your own opinion. Nevertheless, there is nothing special about code. it's still text and it can still be edited (as long as you improve it and don't introduce errors). If you don't like it, roll it back.
    – terdon
    Jan 18, 2017 at 10:04
  • Just a side note, I know I am sensitive to editing my code, and what I say easily explained in that context, but that is really (and honestly) not my point. Jan 18, 2017 at 10:09
  • As already mentioned in chat, I don't see how the site's license: Share — copy and redistribute the material in any medium or format Adapt — remix, transform, and build upon the material, is in contradiction with being restraint in editing code on the post. It just means anyone may take the code, use it, change it under certain conditions. It mentionsnothing at all on the policy on editing code on a post. We are then back to discussing an opinion. Jan 19, 2017 at 7:53
  • @JacobVlijm no, posting an answer constitutes releasing it. It no longer belongs to you, it is now in the public domain under the CC license. Therefore, you can adapt it. Here.
    – terdon
    Jan 19, 2017 at 13:53
  • @terdon We are discussing a policy here. Not what we can do or not. Of course anyone can edit code in any way, even change it 100%. That does not make it bad to be restraint in doing so, and preferably involve the poster to make sure to always respect the original author, as the guidelines suggest. I don't understand btw why you are fighting what seems to be the practiced policy among higher rep users anyway. Jan 19, 2017 at 14:33
  • @JacobVlijm I am not fighting anything at all. I am simply pointing out that there is absolutely no difference between correcting a mistake in grammar and correcting one in code. The same rules and guidelines apply to the entire post irrespective of if it is code, prose, an image or whatever.
    – terdon
    Jan 19, 2017 at 14:35
  • @terdon Now that is a matter of policy and taste. I happen to believe in practice, there is a difference in what is applied already. I can't remember a single occasion of edits on my scripts without getting involved in the process, apart from an occasional inexperienced user. I've had (and edited in) many, many good suggestions though. Jan 19, 2017 at 15:11
  • @JacobVlijm good for you. This question, however, is explicitly asking for site policy and site policy is that anything that can be improved, should be improved. Sure, people can choose to leave a comment or edit, that's up to each user. But policy is that yes, code can be edited.
    – terdon
    Jan 19, 2017 at 15:48
  • 2
    @JacobVlijm then I would ask you to kindly stop this discussion and post your own answer if you believe there is a difference in our positions.
    – terdon
    Jan 19, 2017 at 16:02
  • ? Well, I believe @Zanna's post expresses all quite well, but yes, let's end this then. Jan 19, 2017 at 17:17
3

Whenever editing code/commands, I tend to only make edits that solve typographical/grammatical issues, as opposed to altering how the code/commands could fundamentally work. Or, more accurately, I would only edit a command/code post if it were 100% safe and would not change how anything could execute.

For example, given the below command:

sudo atp install libpackage2-dev

I would:

  • Correct atp to apt, as that what was clearly intended by OP.
  • Not correct the package name to libpackage3-dev, even if that was the actual package intended by OP. This would better be suited as a comment (or even a new answer) instead of an edit.
    • I would, however, edit the package name if it were obvious that the package specified by OP is wrong (e.g. the OP says "install libpackage3-dev:" before the command, the source for the command specifies libpackage3-dev, and so on)

Similarly, given a command like:

modprobe some_module

where some_module is the wrong/deprecated module (instead it's some_linux_module) would elicit a comment, not a correction. The OP may have had a very specific reason for calling some_module instead of some_linux_module, and therefore it could potentially change the outcome of the answer.

0

Just to add the perspective of a scripter

Scripts can vary from a few lines, to a complicated and comprehensive solution, involving many aspects. Especially in the latter case, I am asking editors to be restraint to edit. If you assume this is the result of being possesive, or having difficulties on the principles of sharing as the guidelines of SE describe, please continue reading.

Comprehensive scripts are often the result of a detailed research and testing. Practically every aspect is the result of a decision in context. In many cases, different procedures are tested, and compared on speed, efficiency and reliability in relation with other parts of the script.

Then after posting, the job is not done. In many cases, scripts subsequently run for hours, days, sometimes even weeks or months and on different machines and Ubuntu versions, to make sure the script works as intended, and no side effects occur on longer term and in possibly unforeseen situations. Also practically always, this leads to further editing after posting.

Doing so, I significantly treat my code differently from textual content of an answer, and I am asking editors kindly to act accordingly. If you are willing to do the same, and run thorough and long term tests to see if an edit has issues you might have overlooked, I will highly appreciate and embrace your edit.

If not however, I am asking you to, by all means, mention where in your opinion the code can be improved, but let me edit in your suggestion.

That is, in short, what I call being restraint in editing code.

0

You must log in to answer this question.

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