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

[Junio C Hamano <gitster@pobox.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.

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

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