[RFC] Update coding conventions to restrict use of non-const references

[Pedro Alves]

On 07/12/2018 12:40 PM, Jonathan Wakely wrote:
> On Thu, 12 Jul 2018 at 11:41, Richard Sandiford wrote:
>> +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>
> 
> And the return value of such operators (which also applies to member
> operators, which is the more conventional way to write compound
> assignment operators).
> 
>> +<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
> 
> I understand the objection to using references for out parameters 

FWIW, GDB's conventions (which import GCC's coding conventions) already
suggest avoiding non-const reference output parameters, so this won't
affect us.

But, FWIW, personally, while I used to be all for avoiding non-const
reference output parameters, I no longer am, at least so strongly,
nowadays.

The reason being that the visual distinction can be easily lost with
pointers too anyway:

 // the usual argument is that using pointers for output parameters shows
 // clearly that bar is going to be modified:
 function (foo, &bar);

 // but well, we often works with pointers, and if "bar" is a pointer,
 // we don't get any visual clue anyway either:
 function (foo, bar);

 // which suggests that what really helps is seeing the output
 // variable nearby, suggesting to define it right before the
 // function call that fills it in, and I would go as far
 // as saying that clearer symbol names help even more.  For e.g.:
 B bar_out;
 fill_bar (foo, bar_out);

(an
> alternative to pointers is to return a struct with the wide int result
> and the overflow flag),

+1.  I've been pushing GDB in that direction whenever possible.

> but ...
> 
>> +int *elt = &array[i];  // OK
>> +int &elt = array[i];   // Please avoid
> 
> ... this seems unnecessary. If the function is so long that the fact
> elt is a reference can easily get lost, the problem is the length of
> the function, not the use of a reference.
> 

+1000.  This seems really unnecessary.  References have the advantage
of implicit never-null semantics, for instance.

Pedro Alves