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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: May 22, 2019, 00:17 UTC
Message-ID: <20190522001736.GA219159@google.com>
In-Reply-To: <20190521235212.GA46998@google.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.
	 */

.)

Show 6 quoted lines

>>> +	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