Re: [PATCH v2] grep: provide sane default to grep_source struct

[Jonathan Nieder <jrnieder@gmail.com>]

Hi,

Emily Shaffer wrote:
> On Thu, May 16, 2019 at 06:02:54PM -0400, Jeff King wrote:
>> On Thu, May 16, 2019 at 02:44:44PM -0700, Emily Shaffer wrote:

>>> +	/* TODO: In the future it may become desirable to pass in the name as
>>> +	 * an argument to grep_buffer(). At that time, "(in core)" should be
>>> +	 * replaced.
>>> +	 */

(micronit, likely moot: Git's multi-line comments start with "/*" on
its own line:

	/*
	 * NEEDSWORK: Passing the name in as an argument would allow
	 * "(in core)" to be replaced.
	 */

.)

>>> +	grep_source_init(&gs, GREP_SOURCE_BUF, _("(in core)"), NULL, NULL);
>>
>> Hmm. I don't see much point in this one, as it would just avoid
>> triggering our BUG(). If somebody is adding new grep_buffer() callers
>> that don't use status_only, wouldn't we want them to see the BUG() to
>> know that they need to refactor grep_buffer() to provide a name?
[...]
> Can we think of a reason anybody would want to be able to use it this
> way with the placeholder string?

I agree with Peff here: using NULL puts this in a better place with
respect to Rusty's API design manifesto[1].

With the "(in core)" default, I may end up triggering the "(in core)"
behavior in production, because there is not a clear enough signal
that my code path is making a mistake.  That's problematic because it
gives the end user a confusing experience: the end user cares where
the line comes from, not that it spent a second or two in core.

With the NULL default, *especially* after this patch, such usage would
instead trigger a BUG: line in output, meaning

- if it gets exercised in tests, the test will fail, prompting the
  patch auther to pass in a more appropriate label

- if it gets missed in tests and gets triggered in production, the error
  message makes it clear that this is a mistake so the user is likely
  to report a bug instead of assuming this is deliberate but confusing
  behavior

In that vein, this patch is very helpful, since the BUG would trip
*consistently*, not only when the grep pattern matches.  Failing
consistently like this is a huge improvement in API usability.

It would be even better if we could catch the problem at compile time,
but one thing at a time.

Thanks,
Jonathan

[1] https://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html,
https://ozlabs.org/~rusty/index.cgi/tech/2008-04-01.html