Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Derby Development" <derby-dev@db.apache.org>
Received-SPF: pass (hermes.apache.org: local policy includes SPF record at
 spf.trusted-forwarder.org)
Message-ID: <001101c50959$4824ae70$1401a8c0@rpws002>
From: "RPost" <rp0428@pacbell.net>
To: "Derby Development" <derby-dev@db.apache.org>
References: <BAY2-F41FF492D63028B6166F0B0987E0@phx.gbl>
 <42011314.5090703@debrunners.com>
Subject: Re: code organization
Date: Wed, 2 Feb 2005 10:59:11 -0800
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit

> shahbaz chaudhary wrote:
>
>1. Some of the terms used are not immediately obvious (perhaps just to
me?):
>DRDA (network code?), IAPI (interface api?), (vtit...?), noputresultset
(NoPut ?)

I believe that Dibyendu not only plans on including a glossary in the
documentation work he is doing but that he has already begun work on it.

>2. Is it necessary to keep implementation and interfaces in completely
seperate packages (impl | iapi)...since >implementation packages contain
abstract classes?  What about simply refactoring interface files and adding
an 'I' in >front to distinguish...many implementation classes already have
*Impl* in their name.  Basically this will reduce the >number of directories
and packages one has to traverse to find the right set of code files.

I certainly share your pain in trying to find the right set of code files to
follow what is happening. As Dan suggests, you really need to use an IDE to
assist in this process. Following the raw code manually can only convey, at
best, what is possible. You need to follow the implementation to ascertain
what is actually being done. Obviously, this is because of the way that
implementation classes, abstract classes and interfaces all meld together.
Interfaces don't include variables and abstract methods don't show the
actual code.

I use JBuilder to do the implementation class/package traversal to
understand a specific code hierarchy and then use raw code inspection to get
the bigger architectural picture.

>. . . refactoring the code won't make any functional improvements but it
will be beneficial from a usability >perspective...since large number of
'users' of this code will actually be developers looking to get familiar
with the >code and contribute.

I would suggest that the fact that the original developers already know the
current directory/package structure is the strongest argument for leaving
the structure the way it is.

IMHO that the knowledge and expertise that these original developers have is
far too valuable at this stage of the project to risk diluting. As soon as
any refactoring is done NONE of these experts will be able to provide
assistance until they spend time getting up to speed on the changes that
were done. Thus their ability to contribute is immediately diluted. I'd
rather have the expert resources being used to fix critical problems, work
on new functionality and explain how (and why) things are being done now (as
Dan does so well).

Dibyendu has begun an ambitious project to document this expert knowledge
and his efforts will go a long way towards providing the type of information
you are looking for. So far he is getting excellent and, I dare say,
enthusiastic support from the developers.