Re: DOM and SAX parsing in Ada

[Stephen Leake <stephen_leake@acm.org>]

Nick Roberts <nick.roberts@acm.org> writes:

> Stephen Leake <stephen_leake@acm.org> wrote:
> 
> > > So, I could see very little advantage to making any contributions to
> > > XML/Ada, since it would create two XML/Adas (mine and AdaCore's). Would
> > > that be an advantage to the Ada community?
> > 
> > Big disconnect. Why do you say there would be two? Hmm, apparently you
> > feel you can only contribute if the CVS repository is on SourceForge. Why
> > is that, specifically?
> 
> I told the AdaCore employee that I wanted to make a large number of small
> changes (a lot of comments that would help identify fragments of code, for
> referential maintenance documentation), and he responded that he felt such
> changes were not necessary. I took this to imply (although admittedly he
> didn't say so explicitly) that he wouldn't accept these changes into the
> AdaCore CVS repository. On this basis, I was assuming that I would have to
> create a forked project on some other repository (of course it doesn't have
> to be SourceForge per se).

Ok. So, you could not contribute your particular changes because the
"project architect" did not agree they are necessary.

This is a fact of life when more than one person is on a project.
Somebody has to be the architect (I don't think the "bazaar" model is
appropriate), and everyone else has to agree to live with the
architects rules.

If the architect is a good project manager, they will listen to the
developers, and adjust the rules to maintain a healthy project.

In your particular case, I don't know enough to say whether I would
lobby for what you wanted to do. The statements you have made here
have not had detail; they have just been of the form "the number of
comment lines is too small". I would reject such justifications as
well.

> > > On the subject of comments, I suggested that the amount of
> > > maintenance documention (in the form of comments or in any other
> > > form) was insufficient -- it was nearly nonexistent, in fact --
> > > and the answer was, in essence, that no maintenance
> > > documentation is required, since the code is self-documenting.
> > > I'm afraid, to me, that attitude is unacceptable (and doesn't
> > > seem very professional, frankly).
> > 
> > Well, did you try reading the code? THat is the only thing that matters,
> > not some arbitrary standard of "not enough comment lines". If you can, in
> > fact, understand it, then it _is_ self-documenting.
> 
> Of course I read the code, Stephen!  In the package bodies there are almost
> no comments at all, and there is no other maintenance documentation. The
> code is very complex, and no vaguely self-documenting. 

I guess you are saying "I did not understand the code, and comments
would help".

> The idea that it could be struck me (and still strikes me) as,
> frankly, bizarre.

It's not bizarre to me; it is something I strive for. Because the Ada
compiler checks the code, but it does not check the comments. I
believe Tucker Taft expressed simmilar sentiments at a SigAda several
years ago (something like "good Ada code doesn't need comments").

Again, that's a fact of life when more than one person is on a
project; people will have different opinions about the appropriate
level of code comments.

I often find myself wishing for an introduction to a complex set of
code. But once I figure out the basic structure, I would find such an
introduction annoying, because it would necessarily be inaccurate.
So I would lobby for creating such an introduction in a separate
document, not as code comments.

> > On the other hand, I agree that a lot of AdaCore's code is not
> > well enough documented; I'm thinking of some parts of GtkAda in
> > particular.
> 
> Well, that would seem to be a case in point, then.
> 
> > But the proper response is to contribute good documentation, not just
> > complain.
> 
> I wanted to do precisely that!  I specifically offered to contribute
> maintenance documentation, but this offer seemed to be rejected, in effect,
> by the AdaCore employee I communicated with.

Ok. It is a problem. But not, I think, a sufficient problem to warrant
a fork.

Perhaps if you offered to write a separate introduction document, that
would be accepted.

-- 
-- Stephe