[geos-devel] FileNames + Roadmap

[strk at refractions.net]

On Fri, Mar 10, 2006 at 07:42:03PM +0100, Mateusz Å?oskot wrote:
> Paul Ramsey wrote:
> >Change for changes sake? :)
> 
> I think it's a good time to make big changes, but necessary for easier
> maintenance in future.
> 
> Why?
> - GEOS 3.0.0 will very likely break backward compatibility regarding
> C++ API

Already had, given the huge size of it (the C++ API).
Reducing it is the problem of highest priority if we want
to get a 'maintained' C++ API back.
I virtually dropped it intrudicing the C-API, altought I
still try to keep compatible the subset of the API which
was the only one intentionally documented in Doxygen output
(Geometry, CoordinateSequence, GeometryFactory, GEOSException).

> - currently, strk commits pretty big changes

The *big* changes are basically namespaces additions and headers split.
The former (namespaces addition) is aimed at getting closer
to JTS and possibly includes classes/filename renaming (see below).
The latter (headers split) is aimed at reducing build times,
better documenting the code and opening the road to a reduced
C++ API (by only installing a selected subset of them).

> - currently, GEOS source code is being refactored seriously
> - GEOS 3.0.0 is not released yet, so changes are possible
> - it's better to release big amount of changes at once than release
> them in smaller chuncks in time. Especially that every such chunk is
> going to break backward compatibility, so there is no difference for
> users: once or in pieces, but once sounds better for developers ;-)

The C-API is here for exactly this purpose: allowing us to
spread the refactoring process over multiple releases w/out C-API
users noticing it (yes, C++ users will suffer from this, but
GEOS-3.0.0 is already pending for a too long time).

> Currently, I have to work using VC++ 8.0 because company I work for
> (Taxus SI Ltd.) is going to use GEOS on Windows.
> So, I'm trying to help strk in refactoring and bug fixing job to get
> stable GEOS as fast as possible.

Your help is highly appreciated :)

> >I'll bow to the will of the developers though...
> 
> Me to. I'm not a GEOS developer but just a freelance contributor so my
> word certainly may be not taken under consideration and no problem about
> that. But I hope I'm doing nothing wrong with sharing my opinion and
> trigger a little dicussion :-)))

About FileNames, most cases of camelWithInitialLowercase
are due to name clashes between classes in different namespaces.
For example, in JTS you have multiple Node classes.
In GEOS these have been remaned to Node, planarNode etc.
We also have PlanarGraph and planarPlanarGraph.
Isn't it horrible ?

By introducing additional namespaces we would now be able
to rename those classes and let the names resolver find
correct one (by using namespace directives or explicit qualification).

I already provided some typedefs (typedef planarPlanarGraph PlanarGraph
in namespace planargraph, for example). And I find it much more cleaner.

This way C++ api users won't suffer much for the change, and I think
it's worth reducing the troubles for them :)

I'd like to actually rename the classes instead and provide typedefs
for backward compatibility. This will help transitions (for example
JTS seems to be going to drop what we call PlanarGraph and keep
using what we call planarPlanarGraph. I'd hate to have a
planarPlanarGraph  w/out even a PlanarGraph defined!.

Similar cases are in index/quadtree.
QuadTreeKey, QuadTreeRoot and who knows which other classes are
actually ported by quadtree::Key, quadtree::Root and the like.
In this case we don't have the camelLowerCased problem but
still a non-direct mapping to JTS names.

I think it's important we get as close as possible to JTS
as we want to maintain correctness and improve performance.

For the correctness part we need to work in strict contact
with JTS developers (we're doing already, with pretty much
success).

For the improvement part we'll surely have to change
implementations, but layout would probably do fine.

So to summarize, roadmap could be:

	- SVN (would help step 2, but we can do w/out)

	- headers split with classes/filenames rename
	  when appropriate (JTS-driven)

	- Unit testing (helpful to know
	  how to name them, so worth doing after/togheter with
	  renames)

	- incremental refactoring during all steps
	  (iterators, templates, standard algorithms, reduction
	  of virtual funx calls, to name a few)

--strk;