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
