[LLVMdev] Guidance on using pointers vs. references for function arguments

[David Blaikie]

On Fri, May 16, 2014 at 4:59 AM, Artyom Skrobov <Artyom.Skrobov at arm.com> wrote:
> Thank you David!
>
> To clarify, I'm not trying to push Google style into LLVM, but I believe there should be _some_ guidance on this subject; while the Golden Rule of "do what the rest of the code does" is fine as long as there is some consistent style throughout the code, it's less useful when -- as you indicate yourself -- everyone had historically picked their own.
>
> (My suggested change to CodingStandards.rst did, in fact, mention specifically that Google style should _not_ be used in LLVM.)
>
> By the way, do you have an opinion on the controversy which yielded this discussion -- whether it's advisable to overload e.g. void SwapByteOrder(int*) and int SwapByteOrder(int), the first acting in place, the other modifying a copy and returning it?

That would be an example of Google style (I assumed that's how this
discussion got started, with someone trying to use Google style
mutable argument passing).

For that particular API, I don't think there's enough benefit to even
bother having the mutation version - I'd probably just have the
by-value/return version myself.

Otherwise I'd consider naming them differently, somehow, rather than
using pointer-ness as a means to communicate the difference. As usual,
naming is hard.

- David

>
>
> -----Original Message-----
> From: David Blaikie [mailto:dblaikie at gmail.com]
> Sent: 15 May 2014 19:20
> To: Artyom Skrobov
> Cc: LLVM Developers Mailing List
> Subject: Re: [LLVMdev] Guidance on using pointers vs. references for function arguments
>
> While we don't hold to the Google style of using pointer-ness to
> denote mutability (as well as it necessarily denoting nullability) and
> I'm personally all in favor of using references more pervasively, my
> personal weather prediction here is that this attitude isn't
> prevailing or pervasive enough to enshrine in the style guide.
>
> 'One' place where pointers still pervade is in many particular type
> hierarchies where the APIs just pervasively deal with pointers and
> often care about pointer identity (types, AST nodes of various kinds,
> etc... ) - they end up being passed around quite often by pointer and
> I'm not sure the tide of opinion has adjusted enough to consider all
> those use cases "bad".
>
> But I'm open to being pleasantly surprised if that's not the case.
>
> (short of any change, essentially the Golden Rule of "do what the rest
> of the code does" (where "rest of" is relative - nearby, or whole
> project, etc and leaves scope for developing /slightly/ differing
> conventions in particular areas, which is healthy to a degree - allows
> us to push forward, experiment, etc) which means the Google style of
> pointers to denote mutability is still a no-go as it's not in use and
> isn't likely to gain usage)
>
> On Thu, May 15, 2014 at 3:22 AM, Artyom Skrobov <Artyom.Skrobov at arm.com> wrote:
>> Hello,
>>
>> Carrying on this conversation from llvm-commits:
>>
>>>>>> Would it be reasonable if we name both SwapByteOrder() -- it's
>> difficult
>>>>>> to describe their purpose in any other way -- and make the in-place
>>>>>> function take a pointer, instead of a reference?
>>>>>
>>>>> Pointer is the wrong API: it implies having to check for null.
>>>>
>>>> I see that in general, the choice between pointer parameters and
>> reference
>>>> parameters can mean one of many things: input vs output, change of
>> ownership
>>>> vs no change, validity of NULL, and perhaps more.
>>>>
>>>> For example, Google C++ Style Guide mandates: "All parameters passed by
>>>> reference must be labeled const. [...] it is a very strong convention in
>>>> Google code that input arguments are values or const references while
>> output
>>>> arguments are pointers."
>> (http://google-styleguide.googlecode.com/svn/trunk/
>>>> cppguide.xml#Reference_Arguments )
>>>
>>> I haven't seen much of that around here.
>>>
>>>> I see that LLVM Coding Standards document doesn't touch this subject at
>> all.
>>>> Should we use this opportunity to add to it that in LLVM, the choice
>> between
>>>> pointer parameters and reference parameters is defined by whether NULL is
>> a
>>>> valid input?
>>>
>>> Not sure that's necessary, but feel free to send a proposal to llvmdev.
>>
>> What does the community think about such an addition?
>>
>> ===================================================================
>> --- docs/CodingStandards.rst    (revision 208684)
>> +++ docs/CodingStandards.rst    (working copy)
>> @@ -837,6 +837,21 @@
>>      It's okay to put extra implementation methods in a public class itself.
>> Just
>>      make them private (or protected) and all is well.
>>
>> +Use References for Non-null Function Arguments
>> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> +
>> +Using a pointer for a function argument implies that the function must
>> treat
>> +NULL input in a sensible way. Where such check is unpractical (e.g. when
>> every
>> +call site is known to pass a non-null input), or when you want to express
>> it in
>> +the function signature that nullptr is not a valid input, use a reference
>> +argument instead.
>> +
>> +This is an application of "Use references when you can, and pointers when
>> you
>> +have to." maxim from the C++FAQ. Avoid using the pointers vs. references
>> +distinction to convey other meanings, e.g. to mark the distinction between
>> +input and output arguments, as may be advised by other style guides.
>> +
>> +
>>  .. _early exits:
>>
>>  Use Early Exits and ``continue`` to Simplify Code
>> ===================================================================
>>
>>
>>
>>
>>
>> _______________________________________________
>> LLVM Developers mailing list
>> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
>
>
>
>