Re: [RFC] GSObjCRuntime API conventions

[Kazunobu Kuriyama]

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.
>
>
> 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. 

I didn't blame David for that at all (if taken so, I apologize it).
Descriptive function names are complements to real documentation, of
course, not substitutions for it.

> > 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. 

I was talking about the interface, not the implementaion. It is a peace
of cake to extract code duplication here and there to create a helper 
function/method, isn't it?  So I'm not sure why the argment supports
the preference to the small API.  It's a different story...

> > 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,
...).

> 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).

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.

Regards,
- Kazunobu Kuriyama