G-wrap 1.9 public API (goops, generics, and modules).

[Rob Browning]

(I've cc'ed this to guile-devel too, because I'd like to see if any
 people more familiar with goops, generics, and guile modules have any
 comments.  I'd be more than willing to go with the "preferred"
 approach here since I don't have deep experience with generic
 functions in public APIs...)

[guile-devel: this is part of a discussion of the upcoming major
 overhaul of G-wrap which Andreas has been working on for a while, and
 which has some fairly interesting changes, but right now we're
 just discussing public API naming issues.]

Andreas Rottmann <address@hidden> writes:

> Rob Browning <address@hidden> writes:

>> for files and "close" for accounts. As an example, I'd even be a
>> little uncomfortable defining "close" for files and "close" for
>> accounts.  Given the possibilities afforded by subclassing, it can
>> be very hard to tell what a given piece of code like this might do:
>>
>>  (for-each (lambda (f) (close f)) items)
>
> This should be (for-each (lambda (file) (close file)) items) 
>
> or the same with "account"; I think if you write it this way, it's
> clear enough. When you use "short" names, you should/must make your
> code clear via naming variables appropriatly.

To some extent, my concern wasn't just with the possible difficulty
reading the code, I was also concerned about the potential for
confusion in code like the above if a bunch of different modules all
export "close" for possibly widely differing classes, especially if
code starts using those modules and subclassing from those clases, and
possibly evem more so if there's any multiple inheritance[1].  With
sufficiently specific function names, one just doesn't have to worry
about that much.

Though perhaps this just isn't a big problem in practice, and it might
well be something I change my mind about.  I must admit I haven't had
a lot of relevant experience since all of my serious generic function
work has been in RScheme and CLOS, and there we tended to avoid any
generic names.  (RScheme also has the limitation of single, first
argument dispatch, so you have to be even more careful.)

[1] but I'd forgotten about guile's generic collision handling which
    you mention below, which I don't fully know about yet, and which
    might help ameliorate the concerns.

> I basically agree, but see above. Encoding the argument type in the
> function name is what I want to avoid, since it is just useless
> typing IMO, and unecessary with GOOPS.

All other things being equal, I have no argument against shorter
names, but I also don't mind more typing whenever it helps, and I *do*
find it nice to be able to grep or incremental search for invocations
easily.  I may well just be less averse to more explicit names than a
lot of people.

> If you think of a mainstream OO language, like Python, you wouldn't
> do this:
>
> class File:
>   def close_file():
>     ...
>
> but 
>
> class File:
>   def close():
>     ....
>
> I tend to think about generic function names *mostly* the same way as
> about "mainstream" OO method names...

Hmm, I tend to think about them somewhat "dually", depending on the
context.  In addition to the above, I also think of them like this
(presuming some nonexistent syntax):

  void operator[close](File f);

i.e. in terms of operator overloading, and I've had enough unpleasant
experiences with C++ overloading to be a little skittish.

> I agree that these names are a bit overly generic. I'll quote the list
> of maybe too generic (g-wrap) exports here, so we can discuss about
> name changes.
>
>    description
>
> I think that can be justified since the semantic operation would be
> "returns the description, which is a string".

I'm still hesitant about really generic names outside of guile core.
I wouldn't be quite as hesitant if guile itself had defined a
documentation generic for use in its global documentation
infrastructure, and if it had, or adds one later, then I presume we'd
have trouble here.

>    typespec 
>    c-name
>    argument-count input-argument-count optional-argument-count
>    arguments argument-types
>    return-type return-typespec
>    generic-name 
>    class-name type options c-type-name all-types add-option!
>    var wrapped-var
>    visible? default-value number name render no-op?

> Hmm, variable-name and wrapped-variable-name? A bit long, but
> bearble I think.

Of course my quickest solution would just be to suggest a gw-, gw/, or
gw: prefix for these exported names, i.e. in this case, gw-var and
gw-wrapped-var?.  That doesn't mean that we can't still use
non-prefixed versions internally.  (Alternately, we could just stick a
g-wrap specific bit into the names, prefix or not,
i.e. default-gw-value.)

Don't get me wrong, I agree that prefixes are uglier[2], but for
public APIs they do have the advantage of being very predictable for
the user.  Users know they won't even have to think about problems if
they don't name something using g-wrap's prefix, and prefixes are also
something that people who don't like them can just strip off at import
time (if use-modules supports that now -- or is that only in ttn's
version?).

[2] not enough to really bother me, but I assume not everyone feels
    that way.

Then again, I'm not all that set on prefixes.  I just want to "do
something reasonable", whatever that is :>

>> (Oh, and given what I've grokked so far, nice work BTW.)
>>
> Thanks!
>
> Andy
> -- 
> Andreas Rottmann         | address@hidden      | address@hidden | 
> address@hidden
> http://yi.org/rotty      | GnuPG Key: http://yi.org/rotty/gpg.asc
> Fingerprint              | DFB4 4EB4 78A4 5EEE 6219  F228 F92F CFC5 01FD 5B62

-- 
Rob Browning
rlb @defaultvalue.org and @debian.org; previously @cs.utexas.edu
GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4