Re: [PATCH v2] CodingGuidelines: a handful of error message guidelines

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 28, 2024, 09:28 UTC
Message-ID: <xmqq34jbogg3.fsf@gitster.g>
In-Reply-To: <CAPig+cSXGreymhni_J8TZ56rp+VZB_Z7ekaRtwFdxE3a2QWS5w@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

>> + - Unless there is a compelling reason not to, error messages from the
>> +   Porcelain command should be marked for `_("translation")`.
>
> Here you capitalize "Porcelain" but below, "plumbing" is all lowercase.

;-) I think that is how we spell them in our documentation when we contrast them against each other.

Show 16 quoted lines

>> + - Error messages from the plumbing commands are sometimes meant for
>> +   machine consumption and should not be marked for `_("translation")`
>> +   to keep them 'grep'-able.
>
> Using the same example, `_("translation")`, for both the "should be"
> and "should not be" cases may very well confuse readers. (It certainly
> confused me.) Perhaps mirroring the example of an item earlier in the
> list would be clearer:
>
>     - Unless there is a compelling reason not to, error messages from
>       porcelain commands should be marked for translation, e.g.
>       `die(_("bad revision"))`
>
>     - Error messages from plumbing commands are sometimes meant for
>       machine consumption, thus should not be marked for translation,
>       e.g. `die("bad revision")`

Thanks, that is much better. Let me steal it verbatim in the hopefully final reroll.

Show 7 quoted lines

>> + - BUG("message") are for communicating the specific error to
>> +   developers, and not to be translated.
>
> Okay, although could be slightly more explicit:
>
>     - BUG("message") is for communicating a specific failure to
>       developers, not end-users, thus should not be translated.

The way I read your rewrite is that the "communitation" mentioned is between the program and the user who saw the message. I wanted to say that the message is seen first by an end-user, and then is communicated to developers. And not translating is one way to make sure the message is not mangled, and stays grep-able, during the game of telephone.

Would this work better?

  - In order to help the user who saw BUG("message") to accurately
    communicate it to developers, do not mark them for translation.

Thanks.