Re: [PATCH/RFC][GSoC] make "git diff --no-index $directory $file" DWIM better.

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Mar 15, 2015, 21:28 UTC
Message-ID: <CAPig+cRFCktpG2ksNnRZiFxDqmQnq38MafkA1E-LC6CHtcuk9g@mail.gmail.com>
In-Reply-To: <CAHLaBN+RVpDrG9OewUS7LCYaEOvVqsTY3znapgMj7VrMJWHaDw@mail.gmail.com>

[re-adding cc:git]

On Sun, Mar 15, 2015 at 2:45 PM, Yurii Shevtsov <ungetch@gmail.com> wrote:

Show 33 quoted lines

>> On Sun, Mar 15, 2015 at 11:35 AM, Yurii Shevtsov <ungetch@gmail.com> wrote:
>>> make "git diff --no-index $directory $file" DWIM better.
>>
>> Specify the area affected by the change, followed by a colon, followed
>> by the change summary. Drop the period at the end. So, something like:
>>
>>     diff: improve '--no-index <directory> <file>' DWIMing
>>
>>> Changes 'git diff --no-index $directory $file' behaviour.
>>> Now it is transformed to 'git diff --no-index $directory/&file $file'
>>> instead of throwing an error.
>>
>> Write in imperative mood, so "Change" rather than "Changes". By
>> itself, the first sentence isn't saying much; it would read better if
>> you combined the two sentences into one.
>
> Got it! My commit message requires improvements
>>> ---
>>> -       if (mode1 && mode2 && S_ISDIR(mode1) != S_ISDIR(mode2))
>>> -               return error("file/directory conflict: %s, %s", name1, name2);
>>> +       if (mode1 && mode2 && S_ISDIR(mode1) != S_ISDIR(mode2)) {
>>> +               struct strbuf dirnfile;
>>
>> Is this name supposed to stand for "dir'n'file", a shorthand for
>> "dir-and-file"? Perhaps a simpler more idiomatic name such as "path"
>> would suffice. Also, you can initialize the strbuf here at point of
>> declaration:
>>
>>     struct strbuf path = STRBUF_INIT;
>
> Yes it is supposed to be "dir-and-file" I thought "path" isn't
> descriptive enough because it could be path to dir. But if you insist,
> no problems

The reason I asked was because it is not uncommon for variable names with an 'n' suffix to mean "length" of something, so the 'n' in 'dirn' was a bit confusing. I personally find the idiomatic name 'path' easier to grok, however, Junio, of course, has final say-so. It's okay to argue for your choice in naming if you feel strongly that it is better.

Show 19 quoted lines

>>> +               const char *dir, *file;
>>> +               char *filename;
>>> +               int ret = 0;
>>> +
>>> +               dir = S_ISDIR(mode1) ? name1 : name2;
>>> +               file = (dir == name1) ? name2 : name1;
>>> +               strbuf_init(&dirnfile, strlen(name1) + strlen(name2) + 2);
>>
>> Unless this is a performance critical loop where you want to avoid
>> multiple re-allocations, it's customary to pass 0 for the second
>> argument. Doing so makes the code a bit easier to read and understand,
>> and avoids questions like this one: Why are you adding 2 to the
>> requested length? I presume that you're taking the "/" and NUL into
>> account, however, strbuf takes NUL into account on its own as part of
>> its contract, so you probably wanted to add only 1.
>
> Yes I thought about performance. I thought it is reasonable since I
> always know size of resulting string. Checked strbuf.c one more time,
> yoг are right I should really add only 1

A few reasons I probably would just pass 0 in this case: (1) this string construction is not performance critical; (2) a person reading the code has to spend extra time double-checking the math; (3) the math may become outdated if someone later alters the string construction in some way, thus it's a potential maintenance burden; (4) terser code tends to be easier to read and understand at a glance, so the less verbose the code, the better.

However, as usual, it's entirely acceptable to argue for your version if you feel strongly about it.

Show 16 quoted lines

>>> +               strbuf_addstr(&dirnfile, dir);
>>> +               if (dirnfile.buf[dirnfile.len - 1] != '/')
>>
>> I don't know how others feel about it, but it makes me a bit
>> uncomfortable to see potential access of array item -1. I suppose, in
>> this case, neither name will be zero-length, however, I'd still feel
>> more comfortable seeing that documented formally, either via assert():
>>
>>     assert(dirnfile.len > 0);
>>     if (dirnfile.buf[dirnfile.len - 1] != '/')
>>
>> or:
>>
>>     if (dirnfile.len > 0 && dirnfile.buf[dirnfile.len - 1] != '/')
>
> My fault again