llvm dev - May 2014 - [LLVMdev] Guidance on using pointers vs. references for function arguments

On May 26, 2014, at 8:21 PM, Chandler Carruth <chandlerc at google.com>
wrote:
> 
> On Mon, May 26, 2014 at 7:41 PM, Andrew Trick <atrick at apple.com>
wrote:
> On May 26, 2014, at 5:02 PM, Chandler Carruth <chandlerc at
google.com> wrote:
> 
>> 
>> On Mon, May 26, 2014 at 4:43 PM, Andrew Trick <atrick at
apple.com> wrote:
>> This has been discussed before but I can’t find a reference to it. I
could have sworn this was in the coding convention at some point. Here’s what I
remember: during early LLVM development there was an effort to establish the
convention that you described above—use pointer types only when nullptr is
valid. This led to a lot of redundant declarations and annoying taking of
addresses and dereferences. It turns out that the convention doesn’t really help
for most informal/internal APIs. It’s actually no harder to debug a SIGSEGV than
a nullptr check. I also adhered to this convention in a previous project and it
never paid off.
>> 
>> Once you begin working on a piece of code you get a feel for which
types should be passed as pointers and which should be passed as reference. Then
you try to pass types consistently regardless of whether a null input is valid.
For example, some types, like the current context, should never be copied or
passed by value and are obviously not null. That’s lower overhead in practice
forcing callers to convert to a reference whenever we want to skip a null check.
> 
> This last sentence should read: it’s lower mental overhead for the
programmer to use the same type consistently rather than worrying about another
convention to follow at every call.
> 
> I would personally be happy to follow the pointer may be nullptr convention
if it were used consistently. I was just trying to reiterate arguments against
it that I’d seen w.r.t LLVM codebase, and I don’t see much value in forcing the
convention everywhere.
> 
> Certainly.
> 
> My suggestion: unless we have evidence this is confusing people trying to
contribute to LLVM, then it isn't broken as is.
Chandler, Andy's recollection is correct.

I was personally infatuated by this idea and pushed it through a ton of the LLVM
IR APIs (this was many years ago, (in the pre-1.0 days, and then again early in
Clang's development because I'm a slow learner).  It led to all sorts of
weird cases where some arguments to IR objects would be taken by reference and
some by pointer.  It made it impossible to remember whether a given function
took a pointer or a reference, and made for absolute madness trying to program
against the APIs.  It got to the point where literally you had to do a build and
just add the missing &/*'s to get the build to go through.

-Chris


-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20140526/ac78e2da/attachment.html>

On Mon, May 26, 2014 at 8:45 PM, Chris Lattner <clattner at apple.com>
wrote:
> Chandler, Andy's recollection is correct.
>
> I was personally infatuated by this idea and pushed it through a ton of
> the LLVM IR APIs (this was many years ago, (in the pre-1.0 days, and then
> again early in Clang's development because I'm a slow learner).  It
led to
> all sorts of weird cases where some arguments to IR objects would be taken
> by reference and some by pointer.  It made it impossible to remember
> whether a given function took a pointer or a reference, and made for
> absolute madness trying to program against the APIs.  It got to the point
> where literally you had to do a build and just add the missing
&/*'s to get
> the build to go through.
>
I didn't doubt any of Andy's recollection here, and it seemed like we
were
largely in agreement...

Anyways, while inconsistency such as you describe between pointer and
reference arguments can be quite frustrating (as I see it was for you), at
least LLVM is still pretty stunningly inconsistent to this day. I also
don't find it to be a significant burden. Especially with Clang (which
corrects for this pretty much perfectly every time) and other tools, when I
have to fix these issues it is very fast.

Ultimately, (as I said in my prior email) I don't think there is a problem
to solve here because I don't think that any of these things are actively
"bad". Maybe its just the devs I know who don't really have
trouble here,
but its not one of the complaints I hear from others or have myself in
day-to-day development.

If mixing pointers and references for the same type in LLVM's APIs is a
serious problem in your mind, what is your concrete suggestion? What should
the end state look like?
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20140526/c49a019b/attachment.html>

On May 26, 2014, at 9:15 PM, Chandler Carruth <chandlerc at google.com>
wrote:
> 
> On Mon, May 26, 2014 at 8:45 PM, Chris Lattner <clattner at
apple.com> wrote:
> Chandler, Andy's recollection is correct.
> 
> I was personally infatuated by this idea and pushed it through a ton of the
LLVM IR APIs (this was many years ago, (in the pre-1.0 days, and then again
early in Clang's development because I'm a slow learner).  It led to all
sorts of weird cases where some arguments to IR objects would be taken by
reference and some by pointer.  It made it impossible to remember whether a
given function took a pointer or a reference, and made for absolute madness
trying to program against the APIs.  It got to the point where literally you had
to do a build and just add the missing &/*'s to get the build to go
through.
> 
> I didn't doubt any of Andy's recollection here, and it seemed like
we were largely in agreement...
> 
> Anyways, while inconsistency such as you describe between pointer and
reference arguments can be quite frustrating (as I see it was for you), at least
LLVM is still pretty stunningly inconsistent to this day. I also don't find
it to be a significant burden.
It is true in parts, but not broadly.  If you look at LLVM, for example, pretty
much all of the IR stuff takes pointers, even in places where they should
"obviously" be references: IRBuilder, ConstantArray::get and other
factories, and many others.  Likewise pretty much the entire Clang AST library
is defined in terms of pointers.

It is true that passes and other local stuff is wildly inconsistent, but the
damage of that is far less than affecting the core IR/AST.
> Ultimately, (as I said in my prior email) I don't think there is a
problem to solve here because I don't think that any of these things are
actively "bad". Maybe its just the devs I know who don't really
have trouble here, but its not one of the complaints I hear from others or have
myself in day-to-day development.
> 
> If mixing pointers and references for the same type in LLVM's APIs is a
serious problem in your mind, what is your concrete suggestion? What should the
end state look like?
I'm not really sure that we need to "solve" this problem.  Can you
restate exactly what the problem is?  We don't all need the compiler to have
perfectly identical code in every pass, for example.

That said, if I were to lay down a rule, I think the right general rule would
be: pointers for "classes" everywhere, references for value types, and
pass by value when it is >= the efficiency of pass by value for value types.

That said, I still don't see a huge problem being solved here...

-Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20140526/59ed089b/attachment.html>

Hello Chris and Chandler,
> This last sentence should read: it's lower mental overhead
> for the programmer to use the same type consistently rather
> than worrying about another convention to follow at every
> call.
But, the whole point of having this in the Standards is that there is only
one convention to follow -- as opposed to, another convention in every part
of the code!

An infrequent contributor myself, I identify strongly with Chandler's
earlier argument that "the simplicity of a consistent rule [is] far more
appealing than "getting a feel for which types" should be passed as
pointers."

> Maybe its just the devs I know who don't really have
> trouble here, but its not one of the complaints I hear
> from others or have myself in day-to-day development.
I understand that for experienced contributors who work extensively on a
part of LLVM, the "local conventions" can seem natural and
unobtrusive; but
for a newcomer, "getting a feel" for such ambiguous, implicit
conventions is
just a speed-bump in the way of contributing to the project.

It's fair enough to have the balance between the convenience for veterans
and the convenience for novices shifted in favour of the veterans, but I
just want to point out that this trade-off exists.


(FTR, I've browsed through the revision history of CodingStandards.rst and
its predecessor CodingStandards.html, and I couldn't find any traces of the
previous incarnation of pointers-vs-references guidance.)

On 28 May 2014, at 15:46, Artyom Skrobov <Artyom.Skrobov at arm.com>
wrote:
> I understand that for experienced contributors who work extensively on a
> part of LLVM, the "local conventions" can seem natural and
unobtrusive; but
> for a newcomer, "getting a feel" for such ambiguous, implicit
conventions is
> just a speed-bump in the way of contributing to the project.
For experienced contributors *who stay within one part of the code*, this may be
true.  For those of us who work on clang, the back end, and anything in between,
the cognitive load to work out at any particular level which are the types that
are expected to be pointers and which are expected to be references is quite
high, especially as there are a number of things that are in the
usually-pointers category in some parts of the codebase and the
usually-references category in others.

David