Q: Java source and directory structure - 'standard way' ?

[FISH]

Ever have one of those days when you're not sure if it's you who's gone
mad, or the rest of the world?

I have an Open Source project on SourceForge for communication with YSMG
- Yahoo's IM protocol. I keep the project source in three directories,
based upon the code's function: one for the network API code itself, one
for the support APIs (basic chat spam filtering, Swing models, rich text
decoders, etc), and one for the test client built using the network API.

When I compile I use the -d option on Sun's SDK... the compiler builds
the necessary directory tree (if not already there from a previous build)
and places the class files into it.

One or two users have complained that the source is in the wrong direct-
ories and it won't compile. One guy helpfully rearranged the source tree
and mailed me a zip file - telling me this is the 'standard way' to store
Java source.

What they do is they build the package directory tree by hand, place
their .java files into the appropriate directories, and then just
"javac *.java" in each directory of the tree. The result is that, in
the absense of a specified output directory, the class files end up
right next to the source files - but this works because the source
code directory structure has been created to mirror the package names.

This isn't the first time I've seen this done - I've noted a programmer
where I work does the same thing! And although it works, to me it is
less than ideal. I have a hard time accepting that this is the 'standard
way', for several reasons:

1) The compiler should be responsible for organising and creating *ALL*
its output itself - this includes creating any directories which
are needed for its representation of the code. The user should not
need to work this out in advance and provide them.

2) With source and class files intermixed, packing up the source or
creating a Jar becomes a major headache. Surely the output direct
-ories should remain _pure_, containing only those files which form
the package?

3) This scheme pre-supposes that Java compilers will always use direct-
ories to model their package hierarchy - which might not always be
the case.

I can think of a handful of other reasons why I think this scheme is
inferior, but I think I've already made my point...! :-) So, the
question is... Is this *really* the 'standard way' (or conventional
way) of holding Java source - or are all these coders just ignorant
of the -d switch ???
-FISH- ><>

[Missaka Wijekoon]

I think this may be a difference in JDKs. I prefer that the package
source be in all one place and the JDK build the tree as it compiles.

-Misk

FISH wrote:

Ever have one of those days when you're not sure if it's you who's gone
mad, or the rest of the world?

I have an Open Source project on SourceForge for communication with YSMG
- Yahoo's IM protocol. I keep the project source in three directories,
based upon the code's function: one for the network API code itself, one
for the support APIs (basic chat spam filtering, Swing models, rich text
decoders, etc), and one for the test client built using the network API.

When I compile I use the -d option on Sun's SDK... the compiler builds
the necessary directory tree (if not already there from a previous build)
and places the class files into it.

One or two users have complained that the source is in the wrong direct-
ories and it won't compile. One guy helpfully rearranged the source tree
and mailed me a zip file - telling me this is the 'standard way' to store
Java source.

What they do is they build the package directory tree by hand, place
their .java files into the appropriate directories, and then just
"javac *.java" in each directory of the tree. The result is that, in
the absense of a specified output directory, the class files end up
right next to the source files - but this works because the source
code directory structure has been created to mirror the package names.

This isn't the first time I've seen this done - I've noted a programmer
where I work does the same thing! And although it works, to me it is
less than ideal. I have a hard time accepting that this is the 'standard
way', for several reasons:

1) The compiler should be responsible for organising and creating *ALL*
its output itself - this includes creating any directories which
are needed for its representation of the code. The user should not
need to work this out in advance and provide them.

2) With source and class files intermixed, packing up the source or
creating a Jar becomes a major headache. Surely the output direct
-ories should remain _pure_, containing only those files which form
the package?

3) This scheme pre-supposes that Java compilers will always use direct-
ories to model their package hierarchy - which might not always be
the case.

I can think of a handful of other reasons why I think this scheme is
inferior, but I think I've already made my point...! :-) So, the
question is... Is this *really* the 'standard way' (or conventional
way) of holding Java source - or are all these coders just ignorant
of the -d switch ???
-FISH- ><>

--
================================================== ======================
Missaka Wijekoon (a.k.a. Misk) mw*******@RemoveThis.villageEdocs.com
Sr. Software Engineer http://www.villageEdocs.com
VillageEdocs
================================================== ======================

[Missaka Wijekoon]

I think this may be a difference in JDKs. I prefer that the package
source be in all one place and the JDK build the tree as it compiles.

-Misk

FISH wrote:

Ever have one of those days when you're not sure if it's you who's gone
mad, or the rest of the world?

I have an Open Source project on SourceForge for communication with YSMG
- Yahoo's IM protocol. I keep the project source in three directories,
based upon the code's function: one for the network API code itself, one
for the support APIs (basic chat spam filtering, Swing models, rich text
decoders, etc), and one for the test client built using the network API.

When I compile I use the -d option on Sun's SDK... the compiler builds
the necessary directory tree (if not already there from a previous build)
and places the class files into it.

One or two users have complained that the source is in the wrong direct-
ories and it won't compile. One guy helpfully rearranged the source tree
and mailed me a zip file - telling me this is the 'standard way' to store
Java source.

What they do is they build the package directory tree by hand, place
their .java files into the appropriate directories, and then just
"javac *.java" in each directory of the tree. The result is that, in
the absense of a specified output directory, the class files end up
right next to the source files - but this works because the source
code directory structure has been created to mirror the package names.

This isn't the first time I've seen this done - I've noted a programmer
where I work does the same thing! And although it works, to me it is
less than ideal. I have a hard time accepting that this is the 'standard
way', for several reasons:

1) The compiler should be responsible for organising and creating *ALL*
its output itself - this includes creating any directories which
are needed for its representation of the code. The user should not
need to work this out in advance and provide them.

2) With source and class files intermixed, packing up the source or
creating a Jar becomes a major headache. Surely the output direct
-ories should remain _pure_, containing only those files which form
the package?

3) This scheme pre-supposes that Java compilers will always use direct-
ories to model their package hierarchy - which might not always be
the case.

I can think of a handful of other reasons why I think this scheme is
inferior, but I think I've already made my point...! :-) So, the
question is... Is this *really* the 'standard way' (or conventional
way) of holding Java source - or are all these coders just ignorant
of the -d switch ???
-FISH- ><>

--
================================================== ======================
Missaka Wijekoon (a.k.a. Misk) mw*******@RemoveThis.villageEdocs.com
Sr. Software Engineer http://www.villageEdocs.com
VillageEdocs
================================================== ======================

[Raymond DeCampo]

FISH wrote:

What they do is they build the package directory tree by hand, place
their .java files into the appropriate directories, and then just
"javac *.java" in each directory of the tree. The result is that, in
the absense of a specified output directory, the class files end up
right next to the source files - but this works because the source
code directory structure has been created to mirror the package names.

This isn't the first time I've seen this done - I've noted a programmer
where I work does the same thing! And although it works, to me it is
less than ideal. I have a hard time accepting that this is the 'standard
way', for several reasons:

1) The compiler should be responsible for organising and creating *ALL*
its output itself - this includes creating any directories which
are needed for its representation of the code. The user should not
need to work this out in advance and provide them.

2) With source and class files intermixed, packing up the source or
creating a Jar becomes a major headache. Surely the output direct
-ories should remain _pure_, containing only those files which form
the package?

3) This scheme pre-supposes that Java compilers will always use direct-
ories to model their package hierarchy - which might not always be
the case.

I can think of a handful of other reasons why I think this scheme is
inferior, but I think I've already made my point...! :-) So, the
question is... Is this *really* the 'standard way' (or conventional
way) of holding Java source - or are all these coders just ignorant
of the -d switch ???

Fish,

I think to say that organizing the source code in this manner is
standard. Many Java IDEs expect the code to be this way and some
compilers will even emit warnings or errors if it is not.

However, it is not as bad as it seems. You can still use the -d option
even when the source code is arranged this way. So you can still
separate the source code and the class files easily.

Let me address your concerns:

1) The compiler does create the output; the source code and the
directories it is contained in are input.
2) One can still use the -d flag to separate source and class files.
3) I was going to dismiss this concern as silly, but the JLS does
explicitly mention using a database to store classes, so that would have
been wrong of me. However, I doubt this is a serious concern for the
near future.

Finally, let me suggest that you try out ANT. ANT provides a way of
easily specifying how to build your code. It can run the compiler and
jar the files. As an added bonus you can distribute the build script
and everyone working on the code will be able to build it in the same way.

Good luck with your future endeavors,

Ray

[Raymond DeCampo]

FISH wrote:

What they do is they build the package directory tree by hand, place
their .java files into the appropriate directories, and then just
"javac *.java" in each directory of the tree. The result is that, in
the absense of a specified output directory, the class files end up
right next to the source files - but this works because the source
code directory structure has been created to mirror the package names.

This isn't the first time I've seen this done - I've noted a programmer
where I work does the same thing! And although it works, to me it is
less than ideal. I have a hard time accepting that this is the 'standard
way', for several reasons:

1) The compiler should be responsible for organising and creating *ALL*
its output itself - this includes creating any directories which
are needed for its representation of the code. The user should not
need to work this out in advance and provide them.

2) With source and class files intermixed, packing up the source or
creating a Jar becomes a major headache. Surely the output direct
-ories should remain _pure_, containing only those files which form
the package?

3) This scheme pre-supposes that Java compilers will always use direct-
ories to model their package hierarchy - which might not always be
the case.

I can think of a handful of other reasons why I think this scheme is
inferior, but I think I've already made my point...! :-) So, the
question is... Is this *really* the 'standard way' (or conventional
way) of holding Java source - or are all these coders just ignorant
of the -d switch ???

Fish,

I think to say that organizing the source code in this manner is
standard. Many Java IDEs expect the code to be this way and some
compilers will even emit warnings or errors if it is not.

However, it is not as bad as it seems. You can still use the -d option
even when the source code is arranged this way. So you can still
separate the source code and the class files easily.

Let me address your concerns:

1) The compiler does create the output; the source code and the
directories it is contained in are input.
2) One can still use the -d flag to separate source and class files.
3) I was going to dismiss this concern as silly, but the JLS does
explicitly mention using a database to store classes, so that would have
been wrong of me. However, I doubt this is a serious concern for the
near future.

Finally, let me suggest that you try out ANT. ANT provides a way of
easily specifying how to build your code. It can run the compiler and
jar the files. As an added bonus you can distribute the build script
and everyone working on the code will be able to build it in the same way.

Good luck with your future endeavors,

Ray

[FISH]

Raymond DeCampo <rd******@spam-I-am-not.twcny.rr.com> wrote in message news:<qj*******************@twister.nyroc.rr.com>. ..

Let me address your concerns:

1) The compiler does create the output; the source code and the
directories it is contained in are input.
Ah yes, but in Java the package 'hierarchy' is part of the output, so
surely it is more correct that the directories should be constructed
by the compiler - by referencing the source - than created by the
programmer by hand...?

2) One can still use the -d flag to separate source and class files.
Which begs the question, why not use -d all the time? (Then you never
get source and binary intermixed in the same directories!)

Hmmmm... :-)

3) I was going to dismiss this concern as silly, but the JLS does
explicitly mention using a database to store classes, so that would have
been wrong of me. However, I doubt this is a serious concern for the
near future.
I think this pretty much answers the question for me. The fact that
it 'works for now' would suggest to me that this union (in the C
sense of the word) of source and output directories it is not a
desirable way to structure code - and obviously not a 'standard way'.

It works because the compiler will output to the same directory as
the source, if not directed. I'm not sure if this default behaviour
can be guaranteed in future, or on all compilers - so I'd rather
avoid it.

Finally, let me suggest that you try out ANT. ANT provides a way of
easily specifying how to build your code. It can run the compiler and
jar the files. As an added bonus you can distribute the build script
and everyone working on the code will be able to build it in the same way.

I already use Ant, thanks :-) In fact the package I mentioned is
actually used in one of the many extensions to Ant, called ImTask.
Thanks for your input, but I think I'll stick to packaging the source
in a way that makes sense to the project, and leave the compiler to
figure out how it wants to implementent the package 'hierarchy' - it
probably has a better idea than I do :-)

Thanks,

-FISH- ><>

[FISH]

Raymond DeCampo <rd******@spam-I-am-not.twcny.rr.com> wrote in message news:<qj*******************@twister.nyroc.rr.com>. ..

Let me address your concerns:

1) The compiler does create the output; the source code and the
directories it is contained in are input.
Ah yes, but in Java the package 'hierarchy' is part of the output, so
surely it is more correct that the directories should be constructed
by the compiler - by referencing the source - than created by the
programmer by hand...?

2) One can still use the -d flag to separate source and class files.
Which begs the question, why not use -d all the time? (Then you never
get source and binary intermixed in the same directories!)

Hmmmm... :-)

3) I was going to dismiss this concern as silly, but the JLS does
explicitly mention using a database to store classes, so that would have
been wrong of me. However, I doubt this is a serious concern for the
near future.
I think this pretty much answers the question for me. The fact that
it 'works for now' would suggest to me that this union (in the C
sense of the word) of source and output directories it is not a
desirable way to structure code - and obviously not a 'standard way'.

It works because the compiler will output to the same directory as
the source, if not directed. I'm not sure if this default behaviour
can be guaranteed in future, or on all compilers - so I'd rather
avoid it.

Finally, let me suggest that you try out ANT. ANT provides a way of
easily specifying how to build your code. It can run the compiler and
jar the files. As an added bonus you can distribute the build script
and everyone working on the code will be able to build it in the same way.

I already use Ant, thanks :-) In fact the package I mentioned is
actually used in one of the many extensions to Ant, called ImTask.
Thanks for your input, but I think I'll stick to packaging the source
in a way that makes sense to the project, and leave the compiler to
figure out how it wants to implementent the package 'hierarchy' - it
probably has a better idea than I do :-)

Thanks,

-FISH- ><>

[Raymond DeCampo]

FISH wrote:

Raymond DeCampo <rd******@spam-I-am-not.twcny.rr.com> wrote in message news:<qj*******************@twister.nyroc.rr.com>. ..

Let me address your concerns:

1) The compiler does create the output; the source code and the
directories it is contained in are input.

Ah yes, but in Java the package 'hierarchy' is part of the output, so
surely it is more correct that the directories should be constructed
by the compiler - by referencing the source - than created by the
programmer by hand...?

I do not understand your point of view. The package structure is NOT
dictated by the compiler. The programmer dictates to the compiler what
the package structure should be via the "package" directive. So the
package hierarchy is in fact totally controlled by the programmer and
the source.

2) One can still use the -d flag to separate source and class files.

Which begs the question, why not use -d all the time? (Then you never
get source and binary intermixed in the same directories!)

As a matter of fact, I always do. I think most tools also support and
encourage this separation. It has nothing to do with the question of
how one should organize one's source code however.

Hmmmm... :-)

3) I was going to dismiss this concern as silly, but the JLS does
explicitly mention using a database to store classes, so that would have
been wrong of me. However, I doubt this is a serious concern for the
near future.

I think this pretty much answers the question for me. The fact that
it 'works for now' would suggest to me that this union (in the C
sense of the word) of source and output directories it is not a
desirable way to structure code - and obviously not a 'standard way'.

It works because the compiler will output to the same directory as
the source, if not directed. I'm not sure if this default behaviour
can be guaranteed in future, or on all compilers - so I'd rather
avoid it.

I'm not sure what "it works" refers to. We agree that the source and
class files should be separate. I am advocating structuring the source
code based on the package hierarchy; you are advocating structuring the
source code in an arbitrary manner based on logical groupings of
functionality. As far as I can see, my method is a subcase of yours so
I certainly hope you think it works!

Finally, let me suggest that you try out ANT. ANT provides a way of
easily specifying how to build your code. It can run the compiler and
jar the files. As an added bonus you can distribute the build script
and everyone working on the code will be able to build it in the same way.

I already use Ant, thanks :-) In fact the package I mentioned is
actually used in one of the many extensions to Ant, called ImTask.

In that case, let me say thanks for adding to the wealth of open source
tools.

Thanks for your input, but I think I'll stick to packaging the source
in a way that makes sense to the project, and leave the compiler to
figure out how it wants to implementent the package 'hierarchy' - it
probably has a better idea than I do :-)

I hope you take this discussion in the spirit of which it is given --
simply an academic discussion about source code organization. I haven't
meant to insult you in any way nor do I really care how you organize
your source code...it was just a fun topic. After all, the real measure
of code is how it runs, not what directory it lives in.

Ray

[FISH]

Raymond DeCampo <rd******@spam-I-am-not.twcny.rr.com> wrote in message news:<3P*******************@twister.nyroc.rr.com>. ..

FISH wrote:

Raymond DeCampo <rd******@spam-I-am-not.twcny.rr.com> wrote in message news:<qj*******************@twister.nyroc.rr.com>. ..
[snipped...] Which begs the question, why not use -d all the time? (Then you never
get source and binary intermixed in the same directories!)

As a matter of fact, I always do. I think most tools also support and
encourage this separation. It has nothing to do with the question of
how one should organize one's source code however.

Well the question I asked was about programmers who don't use the -d
switch. They visit each source code directory and run "javac *.java"
in it... which works because the compiler defaults to outputing the
class files into the same directory as the source when not directed
otherwise. (It's pretty much the same way one would build code from
C source in multiple directories, or other compiled languages.)

At first I thought this was just a few novice programmers who didn't
understand that the directory structure was just an implementation
detail - it was the way that the original compilers choose to render
their namespace... and indeed it would be just as valid for the
compiler to dispense with the directories altogether and build their
code straight into a Jar file, or even into a database...

Then I started getting a few emails from coders who were clearly
not novices, who said that Java source code is supposed to mirror
exactly the package structure - that this is a standard way of
doing things. All along I had assumed that (physical) source
code directory structure could be independent of the actual (and
logical) namespace structure used within the code --- now a few
coders where telling me this was wrong, and that the 'proper' way
of doing things was to have them match exactly.

I'm not sure what "it works" refers to. We agree that the source and
class files should be separate. I am advocating structuring the source
code based on the package hierarchy; you are advocating structuring the
source code in an arbitrary manner based on logical groupings of
functionality. As far as I can see, my method is a subcase of yours so
I certainly hope you think it works!
Aha - I think I see where we are now. We actually agree, except on a
small point which is just a matter of taste,

The point I was originally asking about was whether the source code
directory structure *must* match exactly the package 'hierarchy' -
and the class files should be built into the same directories as the
source files they came from. What you are saying, as I understand
it, is that the two things should be separate, and it is a matter of
taste (or practicality) as to whether the source layout should match
the package hierarchy.

On that point I whole-heartedly agree.
[snipped...] I hope you take this discussion in the spirit of which it is given --
simply an academic discussion about source code organization. I haven't
meant to insult you in any way nor do I really care how you organize
your source code...it was just a fun topic. After all, the real measure
of code is how it runs, not what directory it lives in.

Actually it was I who was worried that I may have insulted you! I
mean, here was me, asking advice on something - and then being
cheeky enough to start arguing-the-toss with those who choose to
reply. :-)

I think actually, when all the smoke has cleared, we agree. You
like to lay your source files out one way, I like to do it another.
That's exactly how it should be! But we agree that the layout of
the source files - no matter which way - should not be *mandated* by
the namespace 'hierarchy' ... these are two separate structures and
coders should be free to make them as similar or distant as they
want!

I think that, no matter which way you lay things out, you should
*always* use the -d option to build the classes into a clean and
independent structure. (Indeed I think it might be a good idea if
compilers started spitting out a warning if this option isn't set!)
I've added a README to my project's latest download to that effect.

Btw: if you are at all curious... http://jymsg9.sourceforge.net/

Thanks for an interesting discussion.

-FISH- ><>

[Karl von Laudermann]

jo*****@merseymail.com (FISH) wrote in message news:<db*************************@posting.google.c om>...

The point I was originally asking about was whether the source code
directory structure *must* match exactly the package 'hierarchy' -
and the class files should be built into the same directories as the
source files they came from.
Yes to the first question, and no to the second.
What you are saying, as I understand
it, is that the two things should be separate, and it is a matter of
taste (or practicality) as to whether the source layout should match
the package hierarchy.

As I understand it, the source files must (or should) be stored in a
directory structure that matches the package hierarchy, but that
doesn't mean that the class files go into the same directories along
with the source code. Rather, they go into an identically structured
directory tree that can be located anywhere you want. I generally have
a directory called "source" which contains the source code tree, and a
directory called "build" which contains the class file tree, and the
"source" and "build" directories live next to each other. I believe
that this is the "standard" way of doing things, if there is one.

At least, this is the way JBuilder (which I use at work) manages
projects by default, and the way that the example build file for Ant
(which I use at home) does things as well.