[cairo] Re: cairomm API/ABI freeze?

Murray Cumming murrayc at murrayc.com
Wed Aug 16 00:59:23 PDT 2006

> The name of cairo_new_sub_path was definitely chosen to parallel the
> name of cairo_new_path. But with the above deviation, you cannot have
> the same parallelism since cairo_clear_sub_path would be a totally
> incorrect name.

OK. That's worth thinking about then. Maybe we need to change _both_ methods.
> The rationale given for not using "new_path" in cairomm was to avoid
> confusion with the notion of "new" in C++. I'm not a programmer that
> spends enough time with C++ to know if the existence of a function
> named "new_path" without performing a "new" operation would be more
> confusing than the mismatch of cairomm with standard naming of cairo
> functions.

I do think it allows a big chance for confusion. It suggests that the
function allocates an object, which I think it does not.

> I would have expected the appearance of the word "new" as a component
> of a function name to be no more confusing than something like the
> word "operator" appearing within a function name such as
> cairo_set_operator, (where certainly no C++ programmer will confuse
> this with C++ operator overloading).

People would be less likely to think of that as an operator overloading,
but if they see a function called new_something(), they could be forgiven
for thinking that the programmer is telling them that the function does a
new, so they'd better do a delete later. And if that doesn't make sense in
terms of the return type then some people will just get more confused.
It's not difficult to lead inexperienced coders down paths of
misunderstanding like this.


> It's totally your call as the maintainers of cairomm, but I guess I'd
> just ask for one last consideration of whether "new_path" and
> "new_sub_path" might not be usable without having to invent custom
> names for these functions in cairomm.

When this is necessary, let's make sure that we mention the C names in the
documentation for those methods.

Murray Cumming
murrayc at murrayc.com

More information about the cairo mailing list