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)

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?

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