Subject: Client API pedantism

From: Daniel van Vugt <[email-masked]>
Date: Mon, 08 Apr 2013 11:16:35 +0800

Hi all...

It's nice that the Mir client API uses a common pattern that many C 
developers will find familiar:

   namespace_class_method(NamespaceClass *x, ...);

I like it. Just be careful about breaking the pattern. For example:

   mir_surface_create(MirConnection *connection, ...);

Arguably, this should instead be something like:

   mir_connection_createsurface(MirConnection *connection, ...);

Because you're not operating on a surface (mir_surface_whatever) until 
the surface exists.

I'm not sure I'd go as far as proposing a change to the above function 
any time soon. But it's worth keeping consistency in mind for future API 
additions.

- Daniel

---

From: Robert Ancell <[email-masked]>
Date: Mon, 08 Apr 2013 17:30:48 +1200

On 08/04/13 15:16, Daniel van Vugt wrote:
> any time soon. But it's worth keeping consistency in mind for future
> API additions.
>
> - Daniel
>

I agree we should be using namespace_class_method for names. Another one
that breaks this is:

int mir_debug_surface_id(MirSurface *surface);

Which I would expect to be:

int mir_surface_get_debug_id(MirSurface *surface);

I say it's not something that needs to fixed immediately, but can be
migrated over before 1.0.

--Robert

---

From: Thomas Voß <[email-masked]>
Date: Mon, 08 Apr 2013 08:32:38 +0200

> migrated over before 1.0.

Agreed, and Daniel's remark is very valid. Do we have bugs filed for this?

Thomas

---

From: Alexandros Frantzis <[email-masked]>
Date: Mon, 8 Apr 2013 10:34:12 +0300

> migrated over before 1.0.

I would say better sooner than later... The more we wait, the more
instances of the unwanted function name we will have, both in our code
and in foreign code, and the more difficult it will be for us to amend
them all.

Thanks,
Alexandros

---

From: Daniel van Vugt <[email-masked]>
Date: Mon, 08 Apr 2013 15:47:48 +0800

Strictly following the convention feels a bit clunky, like the function 
names become too long:
     mir_connection_createsurface
     mir_connection_create_surface

One way around this, as you'll see in other APIs, is to bend the rules 
for construction and use "mir_create_surface".

I think any of the above approaches are better than "mir_surface_create".

---

From: Thomas Voß <[email-masked]>
Date: Mon, 08 Apr 2013 10:01:27 +0200

>     mir_connection_create_surface

I would rather prefer expressive and complete names adhering to
convention, even if they are clunky. And the amount of typing required
in this case is manageable from my pov.

> I think any of the above approaches are better than "mir_surface_create".

Agreed.