Hi Gilles, That's actually really close to what I ended up with after I started moving the code over. I currently have
* commons-geometry-core * commons-geometry-euclidean * commons-geometry-spherical * commons-geometry-hull * commons-geometry-enclosing So, it's basically split up by space and algorithm. I have the code at https://github.com/darkma773r/commons-geometry/tree/geometry-1. It's not quite ready for a pull request yet but I'm ready for any feedback you or anyone else may have. -Matt ________________________________ From: Gilles <gil...@harfang.homelinux.org> Sent: Thursday, April 12, 2018 9:12 AM To: dev@commons.apache.org Subject: Re: [geometry] Initial Project Structure Hi Matt. On Sun, 8 Apr 2018 02:40:26 +0000, Matt Juntunen wrote: > Hi all, > > I'm forwarding a conversation I had with Gilles on the project > structure for the new commons-geometry project in order to get > feedback on it from everyone. Basically, Gilles is proposing (and has > initially set up) a multi-module project with the following modules > so > far: > > * commons-geometry-bsp > * commons-geometry-euclidean-oned > * commons-geometry-euclidean-twod > * commons-geometry-euclidean-threed > > My thought was that this module break up is too fine-grain and would > make development of code that uses more than one dimension more > difficult than it should be. I was initially picturing having a > single > project for all of the current geometry code since it's all so > closely > related and there's not much of it. However, I can see where Gilles > is > coming from with the previous experience on commons-math. So, I'd > like > to propose an alternative module break up, one that keeps all of the > basic euclidean primitives in one place: > > * commons-geometry-core -- This would contain the code currently > in the packages > * o.a.c.m.geometry > * o.a.c.m.partitioning > * o.a.c.m.geometry.euclidean.oned > * o.a.c.m.geometry.euclidean.twod > * o.a.c.m.geometry.euclidean.threed > * o.a.c.m.geometry.hull > * o.a.c.m.geometry.twod.hull > * o.a.c.m.geometry.enclosing (this is the odd-ball in the > group here so I could be convinced to put this elsewhere) > * commons-geometry-spherical -- This would contain > * o.a.c.m.geometry.spherical.oned > * o.a.c.m.geometry.spherical.twod > > Basically, core would contain the main geometry interfaces (eg, > Point, Space, Vector) as well as all of the basic euclidean > functionality. Most users would only ever need to pull in this > module. > The other modules would be for other spaces, such as spherical, and > other special-purpose code that we have yet to develop. > > Thoughts? Could we have the following modules: * commons-geometry-core * commons-geometry-euclidean * commons-geometry-spherical ? Gilles > Thanks, > Matt Juntunen > > > ________________________________________ > From: Gilles <gil...@harfang.homelinux.org> > Sent: Saturday, April 7, 2018 6:39 PM > To: Matt Juntunen > Subject: Re: Commons Geometry Project Structure > > Hi Matt. > > On Sat, 7 Apr 2018 16:01:32 +0000, Matt Juntunen wrote: >> Hi Gilles, >> >> Yes, I'm picturing a few possible issues with the current structure. >> First, I think that splitting everything up into modules at this >> point >> will inhibit development. For example, each time we add a new >> feature, >> we'll need to worry about either creating a new module or making it >> fit into existing modules. For example, if we make a general utility >> class that makes use of 1D, 2D, and 3D, we'd need to make a separate >> module for it so that it can pull in all of the other dimension >> modules. > > Yes. No problem then? > >> It wouldn't make sense to put it into 3D since it wouldn't >> just be 3D. This is actually the case with the GeometryTestUtils >> class >> I wrote. >> >> Also, the code may be able to be split up now but there's no >> guarantee that features we want to add in the future won't introduce >> circular dependencies and other issues. > > I find it difficult to reason on hypotheticals. > From a developer's POV, circular dependencies are best avoided. > >> Second, having a single module for the current functionality will be >> much more convenient for users. They would just need to pull in a >> single dependency to have access to core functionality for all >> standard dimensions. Plus, a single module makes it much easier to >> discover the overall functionality of the project. This is actually >> how I found out that commons-math had a BSP tree implementation: by >> browsing the code from the source jar. Otherwise, I would have had >> no >> idea. > > I've a bad experience here with "more convenient for users" > arguments: "Commons Math" has remained monolithic primarily > because of it, pulling back development in some packages > because others needed (for some users) to maintain > compatibility with older JVMs. > >> Another practical point in my particular case is that I work on a >> project where every 3rd-party artifact needs to be documented and >> approved. Having a bunch of small artifacts makes this really >> difficult. > > But this is were Java is going (cf. modularization of the JDK > itself in Java 9)! > > Moreover, in the context of Apache and Commons, either one > or more artefacts/modules, the notion of "official release" > is the same and concerns the *source*. > If the issue is with one vs several JAR files, it is readily > solved by creating a so-called "uber" JAR. For user's > convenience, "Commons Geometry" may provide the necessary > maven goal. > >> In short, I think modules are great but not at this point for this >> project. I'm picturing all of the existing geometry code as core >> functionality that should be bundled together. As we add more >> features, we can then make decisions about splitting off separate >> modules. It's too early now. > > My opinion is that it is never too early to think about > developer's convenience; without developers, no code, > and no users. ;-) > Opposite to the path which you outline, I'd suggest > "make modules", and "merge them" when future needs > demonstrate that it will improve the design. > > That being said, I'm just stating what didn't work > out (IMHO) for "Commons Math". But you are going to be > the main driver for development; being the "developer", > your opinion should count more if my arguments do not > convince you. > > Could you please forward this thread to the "dev" ML; > it is important to let others chime in (or to just > leave a trace of such discussions)? > > Thanks again for your involvement, > Gilles > >> Thanks, >> Matt >> ________________________________ >> From: Gilles <gil...@harfang.homelinux.org> >> Sent: Saturday, April 7, 2018 5:21 AM >> To: Matt Juntunen >> Subject: Re: Commons Geometry Project Structure >> >> Hello. >> >> On Sat, 7 Apr 2018 01:21:29 +0000, Matt Juntunen wrote: >>> Hi Gillles, >>> >>> I hope I'm not breaking protocol emailing you directly but this is >>> a >>> quick comment and it didn't seem appropriate for the entire dev >>> mailing list. Let me know if this isn't the correct way to handle >>> this. Anyway, I was just going to start on commons-geometry and I >>> noticed that you had just created a multi-module project structure >>> for >>> it. However, I was picturing a single artifact for all of the >>> geometry >>> code since it's all so closely related. It would also make things >>> easier for downstream users since they would only need to pull in a >>> single dependency. What do you think? >> >> No problem in discussing about it on "dev". :-) >> For creating modules, my basic tenet is that the more the better, >> as it helps thinking about real/conceptual dependencies and makes >> the design clearer; e.g. >> * code is "o.a.c.math4.geometry.partitioning" does not depend >> on anything in other subpackages of "o.a.c.math4.geometry" >> * "o.a.c.math4.geometry.euclidean.oned" does not depend on >> other subpackages except "partitioning" >> * ... >> >> One purpose is to make some mathematical relationships obvious >> in delineating the respective modules, defining scopes, >> refactoring, etc. >> >> Downstream users shouldn't have any problem writing (once) a >> stanza for each of the explicit dependencies which they use in >> their code (what they don't use explicitly will be pulled >> automatically by any modern development tool). >> >> Do you foresee specific problems with that approach? >> >> Best regards, >> Gilles >> >>> >>> Thanks, >>> Matt Juntunen --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
