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

[Eric Sunshine <sunshine@sunshineco.com>]

On Thu, Nov 28, 2024 at 4:28 AM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> >> +   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.

I must not have been paying close enough attention.

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

Let's not spend too much time fine-tuning this. I found your original
clearer than this rewrite. It was just the "and not to be" bit that
made my reading hiccup. Taking your original but substituting in
"thus" may help:

    - BUG("message") are for communicating the specific error to
      developers, thus should not be translated.