Re: [RFC] GSObjCRuntime API conventions

[David Ayers]

Kazunobu Kuriyama wrote:

> Richard Frith-Macdonald wrote:
>
> > 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.

This is the obvious difference which I have requested comments for. 
Thank you.

> > > Secondly, in case we find a bug in such a function and try to fix it,
[...]

This point is pretty much irrelevant, as most of these functions are 
implemented by using each other, which makes many of them rather 
trivial.  I don't believe the maintenance burden is an issue either way. 
 It's more about "many verbose function names" vs. "lean 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. 
>
>
> Yes, it's trivial.  But think about the total amount of time which might
> be spent by people for that.  Also, personally, I don't like to wind
> up a lot of stack frames to know where the variables are set when I
> can't concentrate on debugging for some reasons (sleepy, exhausted,
> ...).

Sorry, I don't think that this is very strong argument for defining an 
API.  API should clear an concise wrt to its usage in code, not wrt to 
debugging.  Having the option of using variables or constants should be 
considered as feature of the API.  In the verbose case, you are forced 
to use 'if' constructs to call the different functions.  If you find 
that this is more readable, there is nothing stopping you from doing the 
same with the collapsed API using constants instead of variables.

> I take down the first point and rely on David in this case.  But I'm
> afraid you get me wrong on the second point, as mentioned above.  Also,
> I can't buy the third point.  My point is the efficiency of the
> maintainance as a whole of the community because I don't think the
> capacity of  human's short-term memory should be accounted as a
> programming environment.  Considering the huge API of GNUstep, adding
> a few functions to it hardly makes difference.

Well this may very well not be the end of it.  There are still a few 
runtime abstractions I've been thinking, of which I simply don't need 
yet, so I'm holding them back.  I asked for comments about the 
conventions now, before the functions start accumulating.

Adding up the responses, I sense a tendency towards the reduced API. 
(This means I have to update and retest before I post the final RFC 
which will contain the patches including documentation.)  Unless you (or 
anyone else) feels strongly that this is the /wrong/ approach, I'd like 
get that done now so this code can go in before the release, OK?

Thanks to everyone for their feedback!  Highly appreciated.

Cheers,
David