Re: [java-gnome-hackers] a possible merge strategy

[Andrew C. <an...@op...>]

On Wed, 2008-10-15 at 16:04 +0200, Stefan Prelle wrote:
> E.g. we took considerable efforts to come up with an API for TreeView or
> TextView which we consider better than that a code generator would
> suggest.

Everyone please keep it straight in their minds that java-gnome 4.0 *is*
substantially generated.

It is only the outside layer that presents the public API that is hand
crafted. The rest, that it wraps, is all generated - and having been a
java-gnome 2.x hacker and later its maintainer, all I can say is Thank
God because writing all that stuff by hand was a nightmare.

So substantially our design goals for 4.0 have been achieved. This
architecture has been validated again and again as we have had to make
minor tweaks. There are of course still a number of TODOs and FIXMEs and
NOTDONEYETs here and there, but really those only need to be addressed
as people run into needing things that run afoul of such minor problems.

        [And I'd just like to put a huge shout out to Vreixo Formoso,
        who did the bulk of the grunt work during 2007 on the parts of
        the code generator that I was reluctant to get into. GLists,
        arrays and out-parameters come to mind. Thanks Vreio!]

Meanwhile, it means we can concentrate on making sure our public API is
sensible in Java terms and stable, protected from the the whims and
variations happening in the underlying libraries. 

Anyway, everything Stefan is saying is totally on point. I just wanted
to quibble on the "generation" issue. java-gnome is a generated binding.
We just have a thin wrapper layer to provide for an abstraction that
shields developers from things that simply do not (and never will)
concern them.

... not to mention the entire engineering design of not doing injection
into generated code; doing so is a HUGE anti-pattern. Ask anyone who has
been around enterprise Java over the last 3-8 years. We went to great
lengths to avoid it.

        [Not to mention it being the foundation of how we can properly
        document our public API. That doesn't seem to have come up.
        5a-Architecture discusses this in detail]

Colin is exposing every last function in GNOME as raw public API.
Goodness. Given that so many of those functions are  deprecated,
unnecessary, unused, superseded, or is just C sugar, this seems
misguided. Given further that the signatures of quite a number of the
functions that *are* desirable are inappropriate in Java makes it really
questionable indeed.

Anyway, the java-gnome code generator already does generate code for
everything it is fed data about - it just doesn't present it as public
API. It could have, and for about 5 minutes at first it was tempting to
do so. It didn't take very long 30 months ago when we were prototyping
things to realize that exposing everything willy-nilly was a terrible
idea. The shape of the public API of a library is for humans to decide.

Most of the time exposing a method in java-gnome is as simple as writing
a single line method - and, by design, code completion against the
package visible generated code makes this no effort whatsoever.

What does take thought is for people to ponder whether the public
signature being presented is indeed appropriate (as usually it is) and
to then invest a few moments into writing some documentation. It's
really not that much to ask... but when trying to explain how something
works quite often you realize that maybe this isn't something that
should be exposed after all.

Anyway, this is all an aside; I just wanted to encourage people to keep
their terminology straight. You know me - the guy who works hard to
point out the difference between users, developers, and hackers. :)

AfC
Sydney

-- 
Andrew Frederick Cowie

Operational Dynamics is an operations and engineering consultancy
focusing on IT strategy, organizational architecture, systems
review, and effective procedures for change management. We actively
carry out research and development in these areas on behalf of our
clients, and enable successful use of open source in their mission
critical enterprises, worldwide.

http://www.operationaldynamics.com/

Sydney   New York   Toronto   London