[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [RFC] GSObjCRuntime API conventions
From: |
Richard Frith-Macdonald |
Subject: |
Re: [RFC] GSObjCRuntime API conventions |
Date: |
Fri, 4 Jun 2004 07:48:29 +0100 |
On 4 Jun 2004, at 07:07, Kazunobu Kuriyama wrote:
Adam Fedor wrote:
On Jun 3, 2004, at 5:09 AM, David Ayers wrote:
The conventions I'd like to have comments on, is the explicit
Class/Instance separation and the explicit Inherited/NotInherited
separation as apposed to collapsing those functions into on which
takes BOOL flags to determine whether Class vs. Instance or
recursive behavior is requested.
I'd rather see a smaller API.
I agree about the smaller API...
Please take the following points into account, too.
First, the smaller API in question definitely requires some
documentation concerning the behavior of the function because it is
supposed to vary depending on the boolean flags. We can skip this
tedious task *for a while* if each function does nothing else other
than one thing described by its name.
David is normally very good about documentation ... I expect that,
either he already has documentation written for these functions,
or he intends to write such documentation before committing them to
CVS (which is what all of us should do when we alter/contribute code).
I'm also not convinced that a larger API is any more self-documenting
than a small one.
Secondly, in case we find a bug in such a function and try to fix it,
we must make sure that the bug fix doesn't introduce another bug by
testing the modified code against all possible combinations of the two
boolean variables (in theory, at least). This suggests any bug fix
for
such a function is generally harder as compared with the API without
boolean parameters.
I disagree ... in these cases I would imagine that most of the code
would
be the same for the cases differentiated by the boolean. So splitting
the
functions up would produce a relatively large amount of code
duplication,
which would mean that any bugs would need to be fixed in two places.
In my experience, that makes it much harder to ensure reliability.
So the smaller API helps us provide more reliable software. I consider
this the second most important argument for keeping the small API.
Thirdly, when the function is invoked with explicit boolean values, say
array = GSObjCGetMethodNames(class, YES, YES);
we wouldn't feel much trouble with it because we do know what the
function is expected to do. To the contrary, suppose we have
array = GSObjCGetMethodNames(class, bool_val, another_bool_val);
where bool_val and another_bool_val are given somewhere, and
that a debugger suggests something goes wrong around there.
To fix it, we first have to check the values of bool_val and
another_bool_val to see if intended values are actually passed to
the function. We could skip this daunting task if the code snippet
above were to be written as
array = GSObjCGetClassMethodNames(class);
from the outset.
I partially agree with this point, but checking argument values in gdb
is trivial, so I don't think the issue is very important in practice.
In summary, I think your first point is mistaken because we will have
documentation, I think the second point is just wrong in this case,
and I think the third point is of minimal importance. So on balance
I prefer the smaller API as it is easier for people to remember a
small number of functions (I consider this the most important reason
for having a small API).