[wwwdocs, PATCH] C++ terminology: the One Definition Rule in diagnostics

[wwwdocs, PATCH] C++ terminology: the One Definition Rule in diagnostics

[David Malcolm]

[-- Attachment #1: Type: text/plain, Size: 1486 bytes --]

Looking at PR ipa/80000, which notes that ipa-devirt.c has two trailing
spaces in:

if (warning_at (
      DECL_SOURCE_LOCATION(TYPE_NAME (DECL_CONTEXT (vtable->decl))),
      OPT_Wodr,
      "virtual table of type %qD violates "
      "one definition rule  ",
      DECL_CONTEXT (vtable->decl)))

and thus emits:

  foo.cc: virtual table of type 'foo' violates one definition rule  

...I think the wording here is a little confusing to a novice C++
coder: it could be misread that the compiler is complaining that there
are "definition rules", and that one of them has been somehow violated
("why aren't you telling me which one?"), as opposed to the correct
reading, that there is a rule that there must be one definition.

There are 5 such diagnostics, all in ipa-devirt.c.

So I think the wording could be improved by adding a "the", and maybe
capitalizing, to make it:

  foo.cc: virtual table of type 'foo' violates the One Definition Rule

(giving a big hint to the user that the "One Definition Rule" is the thing that they should be typing into their search engine, and that "ODR" is an acronym form of it).

I've even seen it hyphenated in some places, which would make it:

  foo.cc: virtual table of type 'foo' violates the One-Definition Rule

or:

  foo.cc: virtual table of type 'foo' violates the one-definition rule


Here's a patch to the terminology part of our conventions, which suggests adding a "the" and capitalizing (but without the hyphen).


Thoughts?
Dave


[-- Attachment #2: odr-terminology.patch --]
[-- Type: text/x-patch, Size: 669 bytes --]

Index: htdocs/codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.80
diff -u -p -r1.80 codingconventions.html
--- htdocs/codingconventions.html	13 Mar 2017 22:01:05 -0000	1.80
+++ htdocs/codingconventions.html	14 Mar 2017 14:08:01 -0000
@@ -448,6 +448,10 @@ and code.  The following table lists som
     <td>"Objective C"</td>
   </tr>
   <tr>
+    <td>"one definition rule"</td>
+    <td>"the One Definition Rule" (capitalize and use "the")</td>
+  </tr>
+  <tr>
     <td>"prologue"</td>
     <td>"prolog"</td>
     <td>Established convention</td>

Re: [wwwdocs, PATCH] C++ terminology: the One Definition Rule in diagnostics

[Jonathan Wakely]

On 14 March 2017 at 14:18, David Malcolm wrote:
> Looking at PR ipa/80000, which notes that ipa-devirt.c has two trailing
> spaces in:
>
> if (warning_at (
>       DECL_SOURCE_LOCATION(TYPE_NAME (DECL_CONTEXT (vtable->decl))),
>       OPT_Wodr,
>       "virtual table of type %qD violates "
>       "one definition rule  ",
>       DECL_CONTEXT (vtable->decl)))
>
> and thus emits:
>
>   foo.cc: virtual table of type 'foo' violates one definition rule
>
> ...I think the wording here is a little confusing to a novice C++
> coder: it could be misread that the compiler is complaining that there
> are "definition rules", and that one of them has been somehow violated
> ("why aren't you telling me which one?"), as opposed to the correct
> reading, that there is a rule that there must be one definition.

Agreed.

> There are 5 such diagnostics, all in ipa-devirt.c.
>
> So I think the wording could be improved by adding a "the", and maybe
> capitalizing, to make it:
>
>   foo.cc: virtual table of type 'foo' violates the One Definition Rule
>
> (giving a big hint to the user that the "One Definition Rule" is the thing that they should be typing into their search engine, and that "ODR" is an acronym form of it).
>
> I've even seen it hyphenated in some places, which would make it:
>
>   foo.cc: virtual table of type 'foo' violates the One-Definition Rule
>
> or:
>
>   foo.cc: virtual table of type 'foo' violates the one-definition rule
>
>
> Here's a patch to the terminology part of our conventions, which suggests adding a "the" and capitalizing (but without the hyphen).
>
>
> Thoughts?

The draft C++ standard switched to consistently hyphenating it about
18 months ago, meaning C++14 doesn't have a hyphen, but C++17 will. So
all-lowercase with a hyphen ("the one-definition rule") matches the
usage in the current draft, and is still clear we're not talking about
one of a set of definition rules.

Re: [wwwdocs, PATCH] C++ terminology: the One Definition Rule in diagnostics

[Martin Sebor]

On 03/14/2017 08:18 AM, David Malcolm wrote:
> Looking at PR ipa/80000, which notes that ipa-devirt.c has two trailing
> spaces in:
>
> if (warning_at (
>       DECL_SOURCE_LOCATION(TYPE_NAME (DECL_CONTEXT (vtable->decl))),
>       OPT_Wodr,
>       "virtual table of type %qD violates "
>       "one definition rule  ",
>       DECL_CONTEXT (vtable->decl)))
>
> and thus emits:
>
>   foo.cc: virtual table of type 'foo' violates one definition rule
>
> ...I think the wording here is a little confusing to a novice C++
> coder: it could be misread that the compiler is complaining that there
> are "definition rules", and that one of them has been somehow violated
> ("why aren't you telling me which one?"), as opposed to the correct
> reading, that there is a rule that there must be one definition.

Heh.  I never would have thought of that.  But you're right.
It reminds me just how wide-spread the convention of dropping
articles is in diagnostics.  Would it make sense to put in
place a guideline to use them consistently?

   https://gcc.gnu.org/wiki/DiagnosticsGuidelines

> There are 5 such diagnostics, all in ipa-devirt.c.
>
> So I think the wording could be improved by adding a "the", and maybe
> capitalizing, to make it:
>
>   foo.cc: virtual table of type 'foo' violates the One Definition Rule
>
> (giving a big hint to the user that the "One Definition Rule" is the thing that they should be typing into their search engine, and that "ODR" is an acronym form of it).
>
> I've even seen it hyphenated in some places, which would make it:
>
>   foo.cc: virtual table of type 'foo' violates the One-Definition Rule
>
> or:
>
>   foo.cc: virtual table of type 'foo' violates the one-definition rule
>

The gcc.po file has these forms:

   msgid "Merge C++ types using One Definition Rule."
   msgid "virtual table of type %qD violates one definition rule"
   msgid "virtual table of type %qD violates one definition rule  "
   msgid "type %qT violates the C++ One Definition Rule"
   msgid "type %qT itself violate the C++ One Definition Rule"
   msgid "%qD violates the C++ One Definition Rule "

I like the last one.  My only question is about capitalization.
GCC is inconsistent about it (not just in this case but in many
others).  Most messages are all lowercase, but some capitalize
established terms or keywords (FORTRAN), some even start with
a capital letter (FORTRAN).  The GCC Diagnostic Guidelines don't
mention capitalization and the GNU Coding Standard recommends
only that messages issued by interactive programs start with
a capital letter and others don't.  It would be nice to have
clarity about what the convention is (or what we agree it
should be) and eventually converge on it in all sources.

Martin

>
> Here's a patch to the terminology part of our conventions, which suggests adding a "the" and capitalizing (but without the hyphen).
>
>
> Thoughts?
> Dave
>