Thread: Help/suggestions about directory structure for my new Java Examples

Hi, I post here not for technical problems but because I would like to receive some suggestions about a new Java project I am planning to start. In particular about the directory/file structure of the project. I think/hope The Cafe is the appropriate section for this.

Premise: currently I have a set of Java Examples developed by me hosted on altervista.org (the link can be found on my site but it's not important now). I had made these examples years ago, and they was developed/structured/deployed in a very "homemade" way.

Now, in the next days, I am planning to rewrite and redesign all my Java Examples from scratch, and I would like also to use a software hosting facility like, for example, Google Code.

My doubts are about how to choose a good/valid directory structure. First of all, I have not just one, two, three, four projects .... I can have dozens, even 60+ examples. For this reason, I can't and don't want to use a "flat" structure like:

svn/
    trunk/
        example1/
            ....
        example2/
            ....

Having a structure like this would be a pain. Some examples are about tables in Swing, some are about graphics, etc... It would be difficult even if I use good naming conventions for the example names.

My examples are generally short and well self-contained, each in average from 1 to 6 Java classes. For these reasons I have not used package names. I think that the use of package names for these examples doesn't give much value and, at opposite, It could only raise problems especially to beginners that want to see/try my examples. The real value I think is about the clear code that shows how to use that component or that API.

For this and other reasons, I can't and don't want to use a single project with an 'src' directory under which to put directories that "reflect" package names (as the standard/common way). Something like:

...../src/the/package/name/ClassName.java

or (with maven)

...../src/main/java/the/package/name/.......
...../src/test/java/the/package/name/.......

Some examples require Java 6, others only Java 5, still others may require an external library (like log4j or an XML parser). I don't want to force someone to get the entire full project just to see or try one small example! And to use the very latest Java version to be sure all examples compile/work.


So in the end I am thinking about a directory structure like this:

svn/
    trunk/
        java-se/
            swing/
                tables/
                    one-example/
                        <some files>   (e.g. README.txt, build.xml for Ant, etc...)
                        src/
                            *.java

Do you think it is a good/valid approach? Do you see any possible/potential problems or simply think there's something better?
Any suggestion or thought is well accepted and appreciated!

Is the directory structure exposed to the user trying to find the example?
If yes, I would also recommend a README in the trunk which serves as an index to tell the user the exact path each example is located at, so the user doesn't have to search through directories if they are just looking for some specific project.

Originally Posted by aussiemcgr

Is the directory structure exposed to the user trying to find the example?

At least for what I see on Google Code, yes, the directory structure is completely "exposed", both directly by Subversion (e.g. http://projectname.googlecode.com/svn/trunk/..... ) and by a Google browse panel (e.g. http://code.google.com/p/projectname/source/browse/.....).
(note: I am not interested in Git/Mercurial)

Originally Posted by aussiemcgr

If yes, I would also recommend a README in the trunk which serves as an index to tell the user the exact path each example is located at, so the user doesn't have to search through directories if they are just looking for some specific project.

The idea of an "index" is obviously good and useful. But I can go even further: I can create a little Java application that generates a simple and nice HTML page from a set of informations gathered from the directory structure and its content.

Into a "section" directory I can create an XML file section.xml that contains for example:

<?xml version="1.0" encoding="ISO-8859-1"?>
<section title="Swing" />

And into an example directory I can create an example.xml:

<?xml version="1.0" encoding="ISO-8859-1"?>
<example title="some name" requires="java6">
  <description>
    <para> ...... </para>
  </description>
</example>

This requires some work, obviously, but for my competence on Java it's not a problem at all.
And in the long run I can benefit from this nice auto-generated page. Do you agree?

Sorry for delay in answering.

Originally Posted by GregBrannon

- ease of finding the desired topic
a searchable index - possibly HTML as you mentioned earlier - is critical

- ease of locating the relevant source code and related topics from the index

- ability to simply and quickly update the entire front end
the index, links, references, etc. should easily accept new topics and remain accurate despite changes to the collection or its structure

I totally agree about this. I will provide a main index/table-of-contents for all examples and each example will have a specific page providing a description, possible screenshots (for GUI examples), requirements, build instructions, etc...

All this will be generated automatically starting from simple XML files using some Java code and an XSLT processor. This requires some initial work for me but once I have a good base template, I can regenerate correctly all support files.

Originally Posted by GregBrannon

- ability to contribute
considering my other suggestions, the collection should allow contributions

This is the only aspect on which i disagree. This examples project is a my personal project. I wouldn't like "contributions" in terms of source code. Obviously I like very much to receive comments, suggestions, critiques and so on. But I will remain the sole owner and committer. Not to mention that all the code for the "indexer" will not be provided. I will use ImageMagick (for screenshot thumbnails) and I am planning to use the Saxon-PE (the professional, paid, version) for XSLT processing. The PE doesn't cost much and has some interesting features that I can use in other public or private projects. I am evaluating the PE just in these days.
So unfortunately for other people will be hard to recreate all the support files. This is one reason for which contributions would not be easy to handle.

Originally Posted by GregBrannon

- consistent source code format
contributors should be given a style guide. since they'll ignore it anyway, source code should be correctly formatted before being added to the collection. appropriately commented code is absolutely essential
- absolutely "correct" source code
includes many of the considerations you've already mentioned, including specifying the Java version required to compile and run the source code

Ok also for this. About source code style/format you have to know that I am so "picky" that in my code there is not even a misplaced { or wrong spacing or name. I'm "terrible" about this ....