Re: [PATCH/coding style] clarify pointers and operators

[Martin Sebor <msebor@gmail.com>]

On 11/27/18 10:20 PM, Sandra Loosemore wrote:
> On 11/26/18 10:59 AM, Martin Sebor wrote:
>> Martin suggested we update the Coding Conventions to describe
>> the expected style for function declarations with a pointer
>> return types, and for overloaded operators.  Below is the patch.
>>
>> As an aside, regarding the space convention in casts: a crude
>> grep search yields about 10,000 instances of the "(type)x" kinds
>> of casts in GCC sources and 40,000 of the preferred "(type) x"
>> style with the space.  That's a consistency of only 80%.  Is
>> it worth documenting a preference for a convention that's so
>> inconsistently followed?
>>
>> Martin
>>
>> Index: htdocs/codingconventions.html
>> ===================================================================
>> RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
>> retrieving revision 1.85
>> diff -u -r1.85 codingconventions.html
>> --- htdocs/codingconventions.html    30 Sep 2018 14:38:46 -0000    1.85
>> +++ htdocs/codingconventions.html    26 Nov 2018 17:59:21 -0000
>> @@ -803,12 +803,17 @@
>>     <td><code>- x</code></td>
>>   </tr><tr>
>>     <td class="left">cast</td>
>> -  <td class="right"><code>(foo) x</code></td>
>> -  <td><code>(foo)x</code></td>
>> +  <td class="right"><code>(type) x</code></td>
>> +  <td><code>(type)x</code></td>
>>   </tr><tr>
>> -  <td class="left">pointer dereference</td>
>> -  <td class="right"><code>*x</code></td>
>> -  <td><code>* x</code></td>
>> +  <td class="left">pointer cast</td>
>> +  <td class="right"><code>(type *) x</code></td>
>> +  <td><code>(type*)x</code></td>
>> +</tr>
>> +</tr><tr>
>> +  <td class="left">pointer return type</td>
>> +  <td class="right"><code>type *f (void)</code></td>
>> +  <td><code>type* f (void)</code></td>
>>   </tr>
>>   </table>
>>
>> @@ -992,6 +997,21 @@
>>   <a href="codingrationale.html#overoper">Rationale and Discussion</a>
>>   </p>
>>
>> +<p>
>> +Note: in declarations of operator functions or in invocations of
>> +such functions that involve the keyword <code>operator</code>
> 
> This sentence would be more readable with a comma inserted here (after 
> <code>operator</code>), I think.
> 
>> +the full name of the operator should be considered as including
>> +the keyword with no spaces in between the keyowrd and the operator
> 
> s/keyowrd/keyword/
> 
>> +token.  Thus, the expected format of a declaration of an operator
>> +is<pre>
>> +    T &amp;operator== (const T &amp; const T &amp);
>> +</pre>
>> +and not for example<pre>
> 
> s/ for example//
> 
>> +    T &amp;operator == (const T &amp; const T &amp);
>> +</pre>
>> +(with the space between <code>operator</code> and <code>==</code>).
>> +</p>
>> +

I've made these changes.

Thanks
Martin