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

[Hubert Tong via llvm-dev]

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/20200324/e075172f/attachment.html>