This is a pretty low priority thing just because we have *so much* code landed by now and in spite of naming there is a reasonably widespread volume of tribal knowledge at this point, but in my experience nearly every newcomer to Mojo is confused by our terminology and syntax. I'm filing this bug to at least have a foundation for discussing possible future changes, even if the conclusion is that such changes are unlikely to be worthwhile.

In particular, I'm thinking about interface endpoint terminology and mojom syntax. The term "InterfacePtr" makes sense if you squint -- it sort of functions like a pointer to a remote impl, but... not really, because reality is more complicated than that. If anything it functions more as a remote *sequenced task runner* but which can only call methods on a specific object.

The term "InterfaceRequest" is pretty ambiguous too. Nothing about these names (Ptr and Request) conveys that they are necessarily intertwined, that they comprise a self-contained end-to-end connection between a concrete object and (one of) its client(s).

In addition, for an interface T, the mojom syntax of T == InterfacePtr and T& == InterfaceRequest has caused quite a bit of confusion. It does not intuitively convey that one is sending a usable interface proxy while the other is sending an endpoint that should be bound to something.

Of course all of this can be remedied with documentation, repetition, trial-and-error, etc, but it might be possible to just make this stuff more intuitive. Straw proposal:

Rename some C++ types:

- mojo::InterfacePtr<T> becomes mojo::Sender<T>
- mojo::InterfaceRequest<T> becomes mojo::Receiver<T>
- mojo::Binding<T> seems fine as-is -- it can bind to a mojo::Receiver<T>.

Change mojom syntax to look more like the templated types:

- T becomes sender<T>
- T& becomes receiver<T>

So in total we have old stuff:

// mojom
interface FooBinder {
  BindFoo(Foo& request, FooClient client);
};

// C++
class FooBinder {
 virtual void BindFoo(FooRequest request, FooPtr client);
};


which becomes:

// mojom
interface FooBinder {
  BindFoo(receiver<Foo> receiver, sender<FooClient> client);
};

// C++
class FooBinder {
  virtual void BindFoo(FooReceiver receiver, FooClientSender client);
};

And finally, it is also very much unclear that mojo::MakeRequest creates an end-to-end object (i.e. a pipe). There was a concerted effort to "bury the pipes" in early Mojo days, that is, to hide the detail that message pipes are involved in interface acquisition and usage. I'm not sure this is beneficial, because we end up having to explain behavior in terms of pipe communication anyway (in particular consider how associated interfaces work). We should consider something like:

  template <typename T>
  mojo::Receiver<T> MakeConnection(mojo::Sender<T>* sender);

or possibly even

  template <typename T>
  std::tuple<mojo::Sender<T>, mojo::Receiver<T>> mojo::MakeConnection();

which would make code read like (assuming C++17):

  auto [foo_sender, foo_receiver] = mojo::MakeConnection<mojom::Foo>();
  auto [foo_client_sender, foo_client_receiver] =
      mojo::MakeConnection<mojom::FooClient>();
  binder->BindFoo(std::move(foo_receiver), std::move(foo_client_sender));

I think the asymmetry of the existing MakeRequest signature is actually surprisingly confusing for people, and it's not at all clear that it's creating a self-contained thing with two equally important, intertwined endpoints, and no other magical side effects. Whether we called it MakePipe, MakeConnection, MakeChannel, MakeIntertwinedSenderAndReceiver, or whatever, is less important to me than the general desire to call it something which represents the complete essence of what's being created.

As one additional nugget of food for thought, there have been repeated complaints that it's difficult to read code and know that it might be sending IPC. I'm a little mixed in response to that, but I do sympathize somewhat. If a Ptr becomes a Sender, then it might not be unreasonable to generate C++ method names with a Send_ prefix, so e.g. "Send_BindFoo()" above.