Following on from:
https://gcc.gnu.org/ml/gcc-patches/2018-07/msg00603.html
this patch is an RFC to mention references in the C++ coding conventions.
It allows const references anywhere they're useful but only allows
non-constant references in contexts that conform to a standard
interface, or when returning a reference to something that is known
to be nonnull.
It looks like there are still very few public functions that use
non-constant references. If the patch is OK, I'll volunteer to
change them.
Thanks,
Richard
Index: htdocs/codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.81
diff -u -p -r1.81 codingconventions.html
--- htdocs/codingconventions.html 2 Jun 2018 21:16:09 -0000 1.81
+++ htdocs/codingconventions.html 12 Jul 2018 10:05:12 -0000
@@ -57,6 +57,7 @@ the conventions separately from any othe
<li><a href="#Over_Func">Overloading Functions</a></li>
<li><a href="#Over_Oper">Overloading Operators</a></li>
<li><a href="#Default">Default Arguments</a></li>
+ <li><a href="#NonConst_Ref">References</a></li>
<li><a href="#Cxx_Inlining">Inlining Functions</a></li>
<li><a href="#Template_Use">Templates</a></li>
<li><a href="#Namespace_Use">Namespaces</a></li>
@@ -996,6 +997,44 @@ Virtual functions should not have defaul
</p>
+<h4><a name="NonConst_Ref">References</a></h4>
+
+<p>
+Const references can be used freely. They are a useful way of reducing
+unnecessary copying or avoiding an impossible copy.
+</p>
+
+<p>
+Only use non-constant references in the following situations:
+</p>
+
+<ul>
+<li>when they are necessary to conform to a standard interface, such as
+the first argument to a non-member <code>operator+=</code></li>
+<li>in a return value, when providing access to something that is known
+to be nonnull</li>
+</ul>
+
+<p>
+In other situations the convention is to use pointers instead.
+</p>
+
+<blockquote>
+<pre><code>HOST_WIDE_INT do_arith (..., bool *overflow); // OK
+HOST_WIDE_INT do_arith (..., bool &overflow); // Please avoid
+
+int *elt = &array[i]; // OK
+int &elt = array[i]; // Please avoid
+</code></pre></blockquote>
+
+<p>
+There are two main reasons for this restriction. The first is to avoid
+an inconsistency with the large body of older (pre-C++) code that uses
+the pointer convention. The second is to maintain a visual distinction
+between the arguments that a function does modify and the arguments that
+it doesn't.
+</p>
+
<h4><a name="Cxx_Inlining">Inlining Functions</a></h4>
<p>
