[CodingStandards] Document coding standard for error and warning messages

[jhenderson]

Summary

In particular, these messages should start with a lower-case letter and should have no trailing period at the end of the last sentence.

See http://lists.llvm.org/pipermail/llvm-dev/2020-March/140178.html for context.

[aaron.ballman]

llvm/docs/CodingStandards.rst

329–330

This advice is not true for diagnostics from the Clang Static Analyzer, where they've chosen to use sentences with capitalization but without punctuation. We should call that style choice out, and clarify that the lowercase/no punctuation style applies to clang as well as clang-tidy.

[jhenderson]

Mention the static analyzer and other tools explicitly.

[hubert.reinterpretcast]

Thanks for doing this. The guidance is really helpful to have.

llvm/docs/CodingStandards.rst

330

Suggestion:
[ ... ] without a period if it were to end in one otherwise. For example, "did you forget ';'?" should still end in a question mark.

345

Should "Clang" be capitalized here?

349

I think a comma before "and so on" is appropriate. Alternatively, use "etc." with a comma.

[jhenderson]

Address review comments.

[hubert.reinterpretcast]

I think this looks good (with a minor comment) but would like to hear from more people first.

llvm/docs/CodingStandards.rst

331

s/punctions/punctuation/;

[aaron.ballman]

Thanks for working on this! (You should wait to commit for others to weigh in as well.)

llvm/docs/CodingStandards.rst

348

pre-existing -> preexisting

[jhenderson]

Address comments. I'll leave this another 24 hours and then commit it, if that's okay?

[dblaikie]

Looks good - thanks!

[rnk]

llvm/docs/CodingStandards.rst

338

If you look at clang diagnostics, I think most of the time we would use a semicolon to separate sentences here, so it would look like this:

error: file.o: section header 3 is corrupt; size is 10 when it should be 20

However, overall this is useful guidance, and if you want to leave this example as is for migrating existing multi-sentence diagnostics, that's OK with me.

[jhenderson]

llvm/docs/CodingStandards.rst

338

Thanks for the comment. I think there's less clear consensus in the tools on what to do about mid-message ends of sentences. I know that there are several messages following <part1>. <part2> style and also <part1>: <part2> etc. Let's leave this as is for now.

[dblaikie]

llvm/docs/CodingStandards.rst

338

If there's lack of consensus it might be preferable for this document not to take a stance on the issue? (either drop this bit entirely, or include alternatives equally - especially if clang's convention isn't shown here (& yeah, I find "this is a fragment. This is a sentence" pretty weird/surprising - given how used to clang's conventions I am), since it's the biggest surface area/usage of diagnostics in the project)

[jhenderson]

llvm/docs/CodingStandards.rst

338

The text itself doesn't state how to separate sentences within the messages, and this example wasn't intended to take a stance on how to form such things, but rather to illustrate that it isn't illegal to have full stops elsewhere (based on the principle that there are existing messages in that form). I think that it's also worth noting that nothing in this is intended to prevent specific projects imposing further guidelines, I guess, so I wouldn't encourage people adopting it for new clang diagnostics, I guess.

If somebody wants to go ahead and further try to get consensus on banning the use of full stops at all in diagnostic messages, I'm not going to stand in the way of that (and then this text should definitely be updated). I just don't have a strong motivation/desire to try to do so.

[dblaikie]

llvm/docs/CodingStandards.rst

338

Fair enough :)

llvm/docs/CodingStandards.rst

.. code-block:: c++
   /// Does something important.
   void example();
 
   // Example.cpp:
 
   /// Builds a B-tree in order to do foo.  See paper by...
   void example() { ... }
 
+Error and Warning Messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clear diagnostic messages are important to help users identify and fix issues in
+their inputs. Use succinct but correct English prose that gives the user the
+context needed to understand what went wrong. Also, to match error message
+styles commonly produced by other tools, start the first sentence with a
+lower-case letter, and finish the last sentence without a period.
+
+For example this is a good error message:
+
+.. code-block:: none
+
+  error: file.o: section header 3 is corrupt. Size is 10 when it should be 20
+
+This is a bad message, since it does not provide useful information and uses the
+wrong style:
+
+.. code-block:: none
+
+  error: file.o: Corrupt section header.
+
+If the tool or project does not have existing functions to emit warnings or
+errors, use the error and warning handlers provided in ``Support/WithColor.h``
+to ensure they are printed in the appropriate style, rather than printing to
+stderr directly.
+
+When using ``report_fatal_error``, follow the same standards for the message as
+regular error messages. Assertion messages and ``llvm_unreachable`` calls do not
+necessarily need to follow these same styles as they are automatically
+formatted, and thus these guidelines may not be suitable.
+
 ``#include`` Style
 ^^^^^^^^^^^^^^^^^^
 
 Immediately after the `header file comment`_ (and include guards if working on a
 header file), the `minimal list of #includes`_ required by the file should be
 listed.  We prefer these ``#include``\s to be listed in this order:
 
 .. _Main Module Header: