Re: [PATCH 1/3] test-lib: Document short options in t/README

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 25, 2014, 17:23 UTC
Message-ID: <xmqqior2mbtx.fsf@gitster.dls.corp.google.com>
In-Reply-To: <53306910.3090807@gmail.com>

Ilya Bobyr <ilya.bobyr@gmail.com> writes:

Show 31 quoted lines

> On 3/24/2014 4:39 AM, Ramsay Jones wrote:
>> On 24/03/14 08:49, Ilya Bobyr wrote:
>>> Most arguments that could be provided to a test have short forms.
>>> Unless documented the only way to learn then is to read the code.
>>>
>>> Signed-off-by: Ilya Bobyr <ilya.bobyr@gmail.com>
>>> ---
>>>  t/README |   10 +++++-----
>>>  1 files changed, 5 insertions(+), 5 deletions(-)
>>>
>>> diff --git a/t/README b/t/README
>>> index caeeb9d..ccb5989 100644
>>> --- a/t/README
>>> +++ b/t/README
>>> @@ -71,7 +71,7 @@ You can pass --verbose (or -v), --debug (or -d), and --immediate
>>>  (or -i) command line argument to the test, or by setting GIT_TEST_OPTS
>>>  appropriately before running "make".
>>>  
>>> ---verbose::
>>> +-v,--verbose::
>> OK
>>
>>> [...]
>>>  
>>> ---valgrind=<tool>::
>>> +-v,--valgrind=<tool>::
>> The -v short option is taken, above ... :-P
>
> Right %)
> Thanks :)
> This one starts only with "--va", will fix it.

Please don't.

In general, when option names can be shortened by taking a unique prefix, it is better not to give short form in the documentation at all. There is no guarantee that the short form you happen to pick when you document it will continue to be unique forever. When we add another --vasomething option, --va will become ambiguous and one of these two things must happen:

 (1) --valgrind and --vasomething are equally useful and often used.
     Neither will get --va and either --val or --vas needs to be
     given.

 (2) Because we documented --va as --valgrind, people feel that they
     are entitled to expect --va will stay forever to be a shorthand
     for --valgrind and nothing else.  The shortened forms will be
     between --va (or longer prefix of --valgrind) and --vas (or
     longer prefix of --vasomething).

We would rather want to see (1), as people new to the system do not have to learn that --valgrind can be spelled --va merely by being the first to appear, and --vasomething must be spelled --vas because it happened to come later. Longer term, nobody should care how the system evolved into the current shape, but (2) will require that to understand and remember why one is --va and the other has to be --vas.

We already have this suboptimal (2) situation between "--valgrind" and "--verbose" options, but a shorter form "v" that is used for "verbose" is so widely understood and used that I think it is an acceptable exception. So

         --verbose::
        +-v::
                Give verbose output from the test

is OK, but "--valgrind can be shortened to --va" is not.