Note preference towards long options only.

1 files changed, 14 insertions, 0 deletions

diff --git a/README b/README
index 9328cb02..5690bc32 100644
--- a/README
+++ b/README
@@ -460,6 +460,20 @@ guidelines in mind:
   difference in speed), but all embedding cases should be documented
   with rationale in comments in the code.
 
+- When completing available options, offer only the most descriptive
+  ones as completion results if there are multiple options that do the
+  same thing.  Usually this means that long options should be preferred
+  over the corresponding short ones.  This way the user is more likely
+  to find what she's looking for and there's not too much noise to
+  choose from, and there are less situations where user choice would be
+  needed in the first place.  Note that this concerns only display of
+  available completions; argument processing/completion for options that
+  take an argument should be made to work with all known variants for
+  the functionality at hand.  For example if -s, -S, and --something do
+  the same thing and require an argument, offer only --something as a
+  completion when completing option names starting with a dash, but do
+  implement required argument processing for all -s, -S, and --something.
+
 - Do not write to the file-system under any circumstances. This can
   create race conditions, is inefficient, violates the principle of
   least surprise and lacks robustness.