Re: [java-gnome-hackers] Mixing generated and hand-written classes

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

On Fri, 2008-03-21 at 01:52 -0400, Colin Walters wrote:
> What would happen at the build process is that we'd parse that Java
> file,

Trying to inject hand written code into generated code is the defining
nightmare that the Enterprise Java world saddled itself with, to their
sorrow. We've spent two years steering clear of it; indeed the entire
architecture was designed with avoiding that anti-pattern in mind.

In any event, the outer edge hand written bindings layer has turned out
to be useful in all sorts of ways. Not the least of which is keeping
control of the public API being presented.

But most of all, that the translation, native, and JNI layers are
generated is simply automating the output of the cumbersome machinery
necessary to get from Java to C. The poor bastards who wrote the 2.x
version of java-gnome did *all* that by hand; we've simply taken the
drudgery part where cut and paste errors are made and streamlined it.

The API presented to humans by java-gnome 4.0 is lovingly crafted by
other humans, which is as it should be.
http://www.operationaldynamics.com/reference/talks/PastPresentFuture/img75.html

> The javadoc appears to be handcoded
> to be nicer, but again I think the approach of generating from gtk-doc
> is the right thing to do,

No. The structure of java-gnome is not a consequence of nice to haves,
it is a consequence of the objectives and design constraints. Human
written JavaDoc is not an option; it is the *entire* point.

The C API documentation discusses C memory management issues which are
meaningless to a Java developer using our library. They refer to
deprecated and obsolete functions and methods, mentions which would be
impossible to strip out in a systematic. But worst of all, that
documentation is reference style, and notorious for being extremely
difficult to learn from. We have adopted the tutorial style for our
documentation, and that's not a 1:1 transform. See
http://java-gnome.sourceforge.net/4.0/doc/design/2b-DesignConstraints.html

++

If you missed them, you might have a reread of
http://java-gnome.sourceforge.net/4.0/objectives.php 
Perhaps also look at
http://www.operationaldynamics.com/reference/talks/PastPresentFuture/img65.html if you weren't at my talk at GUADEC. I suppose I should apologize that I haven't updated any of the doc/design/ material in a long while now; it was all written before we initiated the rewrite and in the early days  as I had a working prototype in place. Looking back over two years' work, though, I'm pretty pleased that we're still holding closely to our aims, and I'm happy with where things stand now.

Ultimately, my mission here is to open up GNOME to an entirely new group
of contributors who have not previously been participants in the Open
Source movement. That's a different optimization than doing things the
way the existing GTK C developers might have done it. That said, it was
pretty nice to get so much support last summer at GUADEC and at Boston
Summit, and last week from the GTK hackers in Berlin. I make a point of
highlighting behaviours that might have been unexpected, and their
support has generally been overwhelming.

One of the great things about the GNOME community over the last three
years has been people's willingness to tolerate our work and to go
through our designs and give us feedback. So I appreciate your notes.

AfC
Toronto

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