Re: [RFC] GSObjCRuntime API conventions

[Kazunobu Kuriyama]

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. 

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.

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.

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.

The bottom line is: the bigger API is better than the smaller one
*in this particular case*, as the bigger API is expected to save
a lot of (invisible) maintenance tasks.

Regards,
- Kazunobu Kuriyama