Re: [PATCH v2] grep: provide sane default to grep_source struct
- Date: Tue, 21 May 2019 17:17:36 -0700
- From: Jonathan Nieder <jrnieder@xxxxxxxxx>
- Subject: Re: [PATCH v2] grep: provide sane default to grep_source struct
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.
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
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.