What is our site policy on code/command edits?

Question

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?

Answer 1

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?)

Answer 2

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 lice¹.

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

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.

---

¹_{I may have paraphrased, slightly.}

Answer 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.

Answer 4

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.