[llvm-dev] [RFC] Coding standard for error/warning messages

[James Henderson via llvm-dev]

Thanks for the feedback. I've now put https://reviews.llvm.org/D76833 up
for review.

On Tue, 24 Mar 2020 at 12:57, Hubert Tong <hubert.reinterpretcast at gmail.com>
wrote:

> On Mon, Mar 23, 2020 at 11:54 AM James Henderson via llvm-dev <
> llvm-dev at lists.llvm.org> wrote:
>
>> Hi all,
>>
>> This came up in a recent review. There is currently no documented style
>> for how to write error messages. For example, should they start with a
>> capital letter or end in a full stop?
>>
> The policy should also mention use of other end-of-sentence punctuation.
> Also, for multi-sentence messages like
> "err_drv_trivial_auto_var_init_zero_disabled".
>
>
>> Consequently, there's quite a bit of inconsistency in our diagnostics
>> throughout the code base.
>>
>> clang typically emits error messages with no leading capital letter and
>> no trailing full stop. For example:
>>
>> C:\>clang
>> "clang: error: no input files"
>>
>> I have suggested this approach be followed in many different reviews,
>> primarily in the LLVM equivalents of the GNU binutils that I typically work
>> on. I'd like to propose that this be followed more widely too, and
>> documented in the coding standards as such. Note, I am not proposing
>> changing existing error messages as part of this. Do people agree with this
>> proposal? If not, what would you prefer to see?
>>
>> As well as "regular" errors you'll see in typical usage, there are 3
>> other kinds of errors that are widely used, with the following output
>> styles:
>>
>> Assertion failures:
>>
>> Assertion failed: false && "this is the message", file <filepath>
>>
>> llvm_unreachable failures:
>>
>> this is the message
>> UNREACHABLE executed at <filepath>
>>
> I understand the proposal is not meant to cover llvm_unreachable; however,
> I do want to point out that the non-full-stop and lowercase style in this
> output format made the message completely unnoticeable for me. A bit less
> so for the assertion failure output.
>
>
>>
>> report_fatal_error failures:
>>
>> LLVM ERROR: this is the message
>>
>> Looking at the existing output, and how they are used, I think
>> llvm_unreachable and assertions do not need standardising, since they are
>> purely for internal usage, whilst report_fatal_error should be standardised
>> to the same as other normal errors (i.e. lower-case first letter, trailing
>> full stop).
>>
> I believe that the document would clearly indicate that the appearance of
> the output differs for llvm_unreachable and assertions, making it so that
> the guidance may not be suitable for those cases (and thus it does not
> apply in those cases).
>
>
>>
>> What do people think?
>>
>> James
>> _______________________________________________
>> LLVM Developers mailing list
>> llvm-dev at lists.llvm.org
>> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20200326/18fba0c3/attachment.html>