[cairo] cairo_image_surface_create_for_data() args

[Carl Worth]

On Thu, 12 May 2005 10:53:42 -0400, Owen Taylor wrote:
> cairo_surface_t *
> cairo_image_surface_create_for_data (unsigned char             *data,
>                                      cairo_format_t             format,
>                                      int                        width,
>                                      int                        height,
>                                      int                        stride);
> 
> While I can see why you'd order the create_for_data() args in that
> order if it was an independent function, as a variant of _create(),
> adding one arg before and one after is just really peculiar.

I actually gave this ordering a bit of thought when I added it,
including the issue you raise here.

> If both args were after, then it would fit well into a 
> "optional arguments" pattern.

I don't think this function fits an "optional arguments" pattern.
I see this case as quite distinct from something like "with_alpha"
which really is an extra optional argument.

With any of the "for_thingy" functions, the thingy is the primary
parameter. Compare to cairo_xlib_surface_create_for_pixmap where the
pixmap comes before the format that describes it.

I think this rule, (primary object before descriptive attributes of
that object), and the association with other for_thingy objects is
stronger than the association between cairo_image_surface_create_for_data  
and cairo_image_surface_create, (in spite of the obvious similarity of
the names).

The primary criteria for determining this kind of thing is what helps
the user remember the right order. My feeling is that there's an
easy-to-remember rule that leads from the name
"cairo_image_surface_create_for_data" to the current order. The
alternative order would require instead remembering the order for
"cairo_image_surface_create" and then transforming it by adding two
parameters. That seems harder to remember by complexity alone.

And then, when adding the two parameters, which comes first? The word
"data" appears in the function name, so adding it first would seem
natural. But that leads to:

	format, width, height, data, stride

which is hideous, (splitting the descriptive attributes and putting
the object being described in the middle). So then you would have to
use:

	format, width, height, stride, data

But I can't think of a simple rule that leads to this order. The only
way to get it is the process described in this email, (which relies on
quite a bit of extra information).

At least, that's the line of thought I went through when I originally
justified the current naming to myself. I'm quite glad to see this
kind of thing put to open debate.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20050512/21a9bb18/attachment.pgp