Welcome to the Java Programming Forums


The professional, friendly Java community. 21,500 members and growing!


The Java Programming Forums are a community of Java programmers from all around the World. Our members have a wide range of skills and they all have one thing in common: A passion to learn and code Java. We invite beginner Java programmers right through to Java professionals to post here and share your knowledge. Become a part of the community, help others, expand your knowledge of Java and enjoy talking with like minded people. Registration is quick and best of all free. We look forward to meeting you.


>> REGISTER NOW TO START POSTING


Members have full access to the forums. Advertisements are removed for registered users.

Results 1 to 5 of 5

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

  1. #1
    Member andbin's Avatar
    Join Date
    Dec 2013
    Location
    Italy
    Posts
    443
    Thanks
    4
    Thanked 122 Times in 114 Posts

    Default 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!
    Andrea, www.andbin.net SCJP 5 (91%) SCWCD 5 (94%)

    Useful links for Java beginners My new project Java Examples on Google Code


  2. #2
    Forum VIP
    Join Date
    Jul 2010
    Posts
    1,707
    Thanks
    25
    Thanked 338 Times in 313 Posts

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

    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.
    NOTE TO NEW PEOPLE LOOKING FOR HELP ON FORUM:

    When asking for help, please follow these guidelines to receive better and more prompt help:
    1. Put your code in Java Tags. To do this, put [highlight=java] before your code and [/highlight] after your code.
    2. Give full details of errors and provide us with as much information about the situation as possible.
    3. Give us an example of what the output should look like when done correctly.

    Join the Airline Management Simulation Game to manage your own airline against other users in a virtual recreation of the United States Airline Industry. For more details, visit: http://airlinegame.orgfree.com/

  3. The Following User Says Thank You to aussiemcgr For This Useful Post:

    andbin (February 1st, 2014)

  4. #3
    Member andbin's Avatar
    Join Date
    Dec 2013
    Location
    Italy
    Posts
    443
    Thanks
    4
    Thanked 122 Times in 114 Posts

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

    Quote Originally Posted by aussiemcgr View Post
    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)

    Quote Originally Posted by aussiemcgr View Post
    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?
    Andrea, www.andbin.net SCJP 5 (91%) SCWCD 5 (94%)

    Useful links for Java beginners My new project Java Examples on Google Code

  5. #4
    Super Moderator
    Join Date
    Jun 2013
    Location
    So. Maryland, USA
    Posts
    6,307
    My Mood
    Mellow
    Thanks
    252
    Thanked 779 Times in 764 Posts

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

    I'm neither a web designer nor experienced in designing a file structure for the purposes you describe, and from my perspective as a potential user, I wouldn't care. In fact, I would be annoyed if I had to be aware of the structure in order to use it. As a potential user, both as a student, contributor, and one who might refer others to the resources you offer, I care about usability and correctness. The structure of the collection should be invisible to the user and irrelevant.

    Where most other collections I've used that are similar to what you describe fail completely or partially:

    - ease of finding the desired topic
    a searchable index - possibly HTML as you mentioned earlier - is critical
    users often don't know what they're looking for, OR they're looking for a general topic area appropriate for them to study based on what they've done so far. for those cases a functional topic list in the order in which they should be studied should be available. all examples for a specific topic area should be capable of being presented together

    - ease of locating the relevant source code and related topics from the index
    links from the index to the source code should be correct; unbroken; cross-referenced; indicating prerequisites, related topics, etc. the index must be USEFUL.

    - ability to contribute
    considering my other suggestions, the collection should allow contributions, but all donations should be strictly moderated to ensure format, correctness, and tested to ensure suitability for the code's described purpose(s)

    - 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

    - 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
    use of the English language should be correct. moderation of the source code should include review and edit of all source code and the collection's administrative elements by a native English language speaker or equivalent

    - 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
    recognize that the notion of "correctness" can evolve with time and may change as the language changes. it's more important that the source code be dated and correct at the time it was written than being constantly updated to conform to language changes

    Hope this helps. Good luck with your project.

  6. The Following User Says Thank You to GregBrannon For This Useful Post:

    andbin (February 17th, 2014)

  7. #5
    Member andbin's Avatar
    Join Date
    Dec 2013
    Location
    Italy
    Posts
    443
    Thanks
    4
    Thanked 122 Times in 114 Posts

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

    Sorry for delay in answering.

    Quote Originally Posted by GregBrannon View Post
    - 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.

    Quote Originally Posted by GregBrannon View Post
    - 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.

    Quote Originally Posted by GregBrannon View Post
    - 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 ....
    Andrea, www.andbin.net SCJP 5 (91%) SCWCD 5 (94%)

    Useful links for Java beginners My new project Java Examples on Google Code

Similar Threads

  1. tree or directory structure
    By pallaviadsul in forum What's Wrong With My Code?
    Replies: 0
    Last Post: July 19th, 2013, 01:34 AM
  2. any good Java System Suggestions?
    By fatika26 in forum Object Oriented Programming
    Replies: 2
    Last Post: February 21st, 2012, 01:42 AM
  3. How to copy files from one directory to another directory
    By kewlkeny in forum File I/O & Other I/O Streams
    Replies: 4
    Last Post: January 25th, 2012, 07:36 AM
  4. Java Class (C++ Structure Like) Help
    By Khadafi in forum Java Theory & Questions
    Replies: 6
    Last Post: January 13th, 2012, 09:07 PM
  5. Setting up Directory Structure in Java Applications
    By Jyotirmoy in forum Member Introductions
    Replies: 0
    Last Post: July 28th, 2011, 06:28 AM