Not to keep all my classes in a single src -> 'package_name' folder I'm creating different sub-packages in order to separate my classes by groups like - utilities, models, activities themselves, etc. I'm not sure if it is a good practice and people do the same in real projects.
Yes, it's definitely standard practice to separate your classes into packages. It's good to establish a convention for how they are separated, to make it easier to find things later. Two common approaches:
Put things into packages based on what they are: model, service, data access (DAO), etc.
Put things into packages based on what function they support (for example, java.io, java.security, etc.
I've used both and keep coming back to the former because it's less subjective (it's always clear whether a class is a model or a service, but not always clear whether it supports one function or another function).
Doing it by class type the way you describe is one way that I've seen in real projects. I don't care for it as much as I used to because when I need to make a change or add a feature I tend to need to have several packages expanded in my IDE. I prefer (when I have the choice) to group classes by feature instead. That way I know where to look for all classes that support that feature.
The convention I prefer is to group classes first by module, then by functionality. For example, you could have the following structure:
com.example.modulea - modulea specific code that doesn't have any real need of a different package
com.example.modulea.dao - data access for module a
com.example.modulea.print - printing for module a
...
com.example.moduleb - moduleb specific code that doesn't have any real need of a different package
com.example.moduleb.dao - data access for module b
com.example.moduleb.print - printing for module b
In this fashion, code is clearer by package.
In the other style, of grouping by pure functionality, the package size tends to be quite large. If your project contains 15 modules, and each module has one or more elements per package, that's at least 15 classes per package. I much prefer clearly separated packages than packages that simply group things because "oh here are some printing utilities that are used for every module but only one module actually uses one of them from this package" - it just gets confusing.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
I am a newbie and just learned that if I define say
package my.first.group.here;
...
then the Java files that are in this package will be placed under my/first/group/here directory.
What is the main purpose of putting some Java files in a package? Also, if I choose to adopt this, how should I group them?
Thank you
EDIT: For anyone who might have the same question again, I just found this tutorial on packages from Sun.
Let's start with the definition of a "Java package", as described in the Wikipedia article:
A Java package is a mechanism for
organizing Java classes into
namespaces similar to the modules of
Modula. Java packages can be stored in
compressed files called JAR files,
allowing classes to download faster as
a group rather than one at a time.
Programmers also typically use
packages to organize classes belonging
to the same category or providing
similar functionality.
So based on that, packages in Java are simply a mechanism used to organize classes and prevent class name collisions. You can name them anything you wish, but Sun has published some naming conventions that you should use when naming packages:
Packages
The prefix of a unique package name is
always written in all-lowercase ASCII
letters and should be one of the
top-level domain names, currently com,
edu, gov, mil, net, org, or one of the
English two-letter codes identifying
countries as specified in ISO Standard
3166, 1981.
Subsequent components of the package
name vary according to an
organization's own internal naming
conventions. Such conventions might
specify that certain directory name
components be division, department,
project, machine, or login names.
Examples:
com.sun.eng
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese
I a large application, you are bound to have two files named exactly the same (java.util.Date and java.sql.Date), especially when you start bringing in third party jars. So basically, you can use packages to ensure uniqueness.
Most importantly, in my opinion, packaging breaks down projects into meaningful segments. So my SQL package has sql-related code, and my logger package handles logging.
In addition to the namespacing mentioned in other answers, you can limit access to methods and fields based on the scope declared on that member.
Members with the public scope are freely accessible, to limit access you normally define them as private (i.e. hidden outside the class).
You can also use the protected scope to limit access to the type and its children.
There is also the default scope (a member with no qualifier has the default scope) which allows child types and types in the same package access to the member. This can be an effective way of sharing fields and methods without making them too widely available, and can help with testing.
For example the method below would be visible to all other members of the same package.
public class Foo {
int doSomething() {
return 1;
}
}
To test the method you could define another type in the same package (but probably a different source location), that type would be able to access the method.
public class FooTest {
#Test
int testDoSomething() {
Foo foo = new Foo();
assertEquals(1, foo.doSomething());
}
}
It allows the program to be composed from multiple different programs/components/libraries, so that their class names will not conflict and the components are easier to organize. See http://java.sun.com/docs/books/tutorial/java/package/index.html
In Java it's customary to name packages as reverse domain names. For example, if your company's domain is "initech.com" and you are making a program called "Gizmo", the package names are typically prefixed "com.initech.gizmo", with subpackages for different components of the program.
Packages are important for giving flexibility of classes separation. They can be used for:
separating projects
separating modules
separating application layers (business, web, dao)
further finer grained code separation
For example
com.mycompany.thisproject.thismodule.web
Could indicate the web layer of some module.
Ultimately, there are 3 core reasons we want to use packages in Java.
1) Easier Maintenance
Organizing classes into packages follows the separation of concerns principle by encapsulation and allows for better cohesion in the overall system design. Moving further, packaging-by-feature allows teams of developers to find relevant classes and interfaces for making changes, supporting vertical-slicing techniques for scaled approaches used in agile methodology. For more information, see blog post: Package your classes by Feature and not by Layers and Coding: Packaging by vertical slice.
2) Provide Package security
Packages allow external access to only public access modifiers on methods in contained classes. Using the protected or no modifier will only be accessible to classes within the same package. For more information, see post:
Which Java access modifier allows a member to be accessed only by the subclasses in other package?
3) Avoid similar naming
Similar to the namespaces of .NET, class names are contained within the scope of their containing package. This means that two mutually exclusive packages can contain classes with the same name. This is because the packages themselves have different names and therefore, the fully qualified names are different. For more information, see tutorial [Naming a Package: The Java Tutorials][3].
From the Wikipedia page on the topic:
"A Java package is a mechanism for organizing Java classes into namespaces similar to the modules of Modula. Java packages can be stored in compressed files called JAR files, allowing classes to download faster as a group rather than one at a time. Programmers also typically use packages to organize classes belonging to the same category or providing similar functionality."
also, if i choose to adopt this, how
should i group them?
This depends largely on the design pattern(s) you will employ in your project. For the most part (particularly, if you're quite new) you'll want to group them by functionality or some other logical similarity.
Other people have provided very Java-specific answers which are fine, but here's an analogy: why do you organize files into directories on your hard drive? Why not just have a flat file system with everything in one directory?
The answer, of course, is that packages provide organization. The part of the program that interfaces with the database is different than the part of the program that displays a UI to the user, so they'll be in different packages.
Like directories, it also provides a way to solve name conflicts. You can have a temp.txt in a couple different directories in the same way that you could have two classes that appear in different packages. This becomes important (1) when you start combining code with other people out there on the internet or (2) even realize how Java's classloading works.
Another important thing about packages is the protected member for access control.
Protected is somewhere between public (everyone can access) and private (only class internal can access). Things marked as protected can be accessed from within the same package or from subclasses. This means that for limited access you don't have to put everything in the same class.
Java is very exact in its implementation. It doesn't really leave room for fudging.
If everyone were to use the same package, they would have to find some "World Wide" way to ensure that no two class names ever collided.
This lets every single class ever written fit into its own "Place" that you don't have to look at if you don't want to.
You may have different "Point" objects defined in 4 different places on your system, but your class will only use the one you expect (because you import that one).
The way they ensure that everyone has their own space is to use your reverse domain, so mine is "tv.kress.bill". I own that domain--Actually I share it with my brother "tv.kress.doug" and even though we share the same domain, we can't have a collision.
If a hundred divisions in your company each develop in Java, they can do so without collision and knowing exactly how to divide it.
Systems that don't do this kind of division seem really flaky to me now. I might use them to hack together a script for something personal, but I'd feel uncomfortable developing anything big without some strict packaging going on.
I was working with Typescript and Javascript and I stopped for a bit thinking about namespaces and how we organize code in Java.
Now, pretty often I see multiple classes with the same purpose, just for use with different data, being placed in different packages with different names.
While placing those classes in different packages is a good practice to maintain the project/module in a good state, why would we have to give them different names? I mean, their purpose is the same.
I can answer this question myself: because often we use those classes inside the same unit and they would clash, thus requiring a long full package specification for one or the other.
But aren't we violating the DRY principle? We should use our directory (package) structure to understand in which domain space those classes works.
As I wrote above, I suppose many developers aren't respecting this DRY principle just to avoid long package names. Then, why are we creating those monstruos package hierarchies?
Googling "Java packages best practices" results in suggestions such as:
com.mycompany.myproduct.[...]
Where do those suggestions come from? Aren't we just wasting space?
We obviously do not want to write that every time.
MyClass myInstance;
com.mycompany.myproduct.mypackage.MyClass myOtherInstance;
But it could have been
myfeature.MyClass myInstance
myotherfeature.MyClass myInstance;
We could even specify the full package for both.
So, where do those best practices come from?
As it has been said, this convention dates back to the first releases of Java.
Name clashes could be easily solved by qualifying the imported dependency (such as a classpath library) classes with their short packages' hierarchy, emphasizing and keeping cleaner our own code. It is also important to remember we have access to the package-level visibility, which seems overlooked nowdays.
As a commenter points out, this convention was established at the very beginning of Java, to allow a global namespace to be used for all classes.
One thing about Java that influences this -- and is different from TypeScript and JavaScript -- the name of a class and its package (as well as all the names of classes and packages it uses) is fixed at compile time. You can't recombine classes into a different hierarchy without modifying their source code. So it's not as flexible as an interpreted language where you can just move the hierarchy around and change the locations from which you load code.
You can, of course, put everything in your application in the top-level package, for example, and be pretty confident you'll get away with it. You'll be able to do that as long as everyone else follows the existing convention. Once they stop doing that, and libraries start putting classes wherever they want, you'll have collisions, and you'll have to change your application. Or libraries will start colliding with each other, and if you don't have the source, you won't really be able to fix it.
So there are good reasons.
My opinion-based part of this -- sticking with conventions and a language's (or platform's) culture makes sense. Even if the conventions are silly, in our view. There's a place for breaking them but the advantages have to be pretty big. Other developers will be used to the convention, tools will make assumptions about the conventions ... usually it makes sense to go with the flow.
Does it really make sense to use getters and setters for every property in Java? If you understand the domain you're using well, it very well might not. But stop doing it and your code isn't going to make sense to other members of your team, you'll have to continuously revisit the decision as people join, and so forth.
If it's a one-person project and always will be, of course, you can do what you want.
I'm looking for different ways to prevent internals leaking into an API. This is a huge problem because once these internals leak into the API; you can run either into unexpected incompatibility issues or into frozen internals.
One of the simplest ways to do so is just make use of different Maven modules; one module with API and one module with implementation. This way it is impossible to expose the implementation from the API.
Unfortunately not everyone agrees this is the best approach; But are there other alternatives? E.g using checkstyle or other 'architecture checking' tools?
PS: Java 9 for us is not usable, since we are about to upgrade to Java 8 and this will be the lowest supporting version for quite some time to come.
Following your checkstyle idea, it should be possible to set up rules which examine import statements in source files.
Checkstyle has built-in support for that, specifically the IllegalImport and ImportControl rules.
This of course works best if public and internal classes can be easily separated by package names.
The idea for IllegalImport would be that you configure a TreeWalker in checkstyle which only looks at your API-sources, and which excludes imports from internal packages.
With the ImportControl rule on the other hand you can define very detailed access rules for the whole application/module in a separate XML file.
It is standard in Java to define an API using interfaces and implement them using classes. That way you can change the "internals" however you want and nothing changes for the user(s) of the API.
One alternative is to have one module (Jar file) for API and implementation (but then again, is it an API or just any kind of library?). Inside one separates classes and interfaces by using packages, e.g. com.acme.stuff.api and com.acme.stuff.impl. It is important to make classes inside the latter package protected or just package-protected.
Not only does the package name show the consuming developer "hey, this is the implementation", it is also not possible to use anything inside (let's omit reflections at this point for the sake of simplicity).
But again: This is against the idea of an API, because usually the implementation can be changed. With this approach one cannot separate API from implementation, because both are inside the same module.
If it is only about hiding internals of a library, then this is one (not the one) feasible approach.
And just in case you meant a library instead of an API, which only exposes its "frontend" (by using interfaces or abstract classes and such), use different package names, e.g. com.acme.stuff and com.acme.stuff.internal. The same visibility rules apply of course.
Also: This way one does not need Checkstyle and other burdens.
Here is a good start : http://wiki.netbeans.org/API_Design
Key point : Do not expose more than you want Obviously the less of the implementation is expressed in the API, the more flexibility one can have in future. There are some tricks that one can use to hide the implementation, but still deliver the desired functionality
I think you don't need any checkstyle or anything like that, just a good old solid design and architecture should be enough. Polymorphism is all you need here.
One of the simplest ways to do so is just make use of different Maven
modules; one module with API and one module with implementation. This
way it is impossible to expose the implementation from the API.
Yes, I totally agree, hide as much as possible, separate your interface in a standalone project.
I always doubt when creating packages, I want to take advantage of the package limited access but at the same time I want to have similar classes divided into packages.
The problem comes when you understand that packages are not hierarchical in Java:
At first, packages appear to be
hierarchical, but they are not.
source
Imagine I have an API defined with its classes at foo.bar, only the classes the API client needs are set public. Then I have another package with some internal objects I need in the API defined at foo.bar.pojos, this classes need to be public so they can be accessed by foo.bar but this means the API client could also access them if the package foo.bar.pojos is imported.
What is the common package politic that should be followed?
I've seen two ways of doing.
The first one consists in separating the public API and internal classes into two different artefacts (jars). The documentation is separated as well, and it's thus easy for the end user to make the distinction between what is internal and what is not. But it sometimes make things more complex to have two jars, two source trees, etc.
The second one consists in delivering a single jar, but have a good documentation allowing to know what's internal and what's not. The textual documentation can explain how to use the API (and thus avoids talking about the internals). And the javadoc can specify that a class is for internal use and is thus subject to changes.
Yes, Java packages don't give you enough control over your dependencies. The classic way to deal with this is to put external APIs in one package and internal implementation classes in another, and rely on people's good sense to avoid creating dependencies on the latter.
With Maven and OSGI, you have an additional mechanism for managing dependencies between modules / bundles of packages. In the case of OSGI, you can explicitly declare some packages as not exported, and an OSGI aware development environment will prevent people creating harmful dependencies. Maven's module support is weaker, but at least it controls dependency cycles.
Finally, you could use custom PMD rules to enforce your project's modularization conventions ... in the same way that there are rules to discourage dependencies on Java's "com.sun.*" package tree.
It is a mess.
Using only what Java itself offers, you have to put everything in the same package. You end up with a single (or a few) packages with lots of classes, and no good way to group them for yourself (but at least that problem does not leak outside). Most people don't do that, though, and as a result, your (as a developer on top of these libraries) public classpath is littered with stuff you should never need to see.
You might like OSGi, which has (and enforces) the concept of bundle-private packages. Those are not exported to the outside world.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
I am a newbie and just learned that if I define say
package my.first.group.here;
...
then the Java files that are in this package will be placed under my/first/group/here directory.
What is the main purpose of putting some Java files in a package? Also, if I choose to adopt this, how should I group them?
Thank you
EDIT: For anyone who might have the same question again, I just found this tutorial on packages from Sun.
Let's start with the definition of a "Java package", as described in the Wikipedia article:
A Java package is a mechanism for
organizing Java classes into
namespaces similar to the modules of
Modula. Java packages can be stored in
compressed files called JAR files,
allowing classes to download faster as
a group rather than one at a time.
Programmers also typically use
packages to organize classes belonging
to the same category or providing
similar functionality.
So based on that, packages in Java are simply a mechanism used to organize classes and prevent class name collisions. You can name them anything you wish, but Sun has published some naming conventions that you should use when naming packages:
Packages
The prefix of a unique package name is
always written in all-lowercase ASCII
letters and should be one of the
top-level domain names, currently com,
edu, gov, mil, net, org, or one of the
English two-letter codes identifying
countries as specified in ISO Standard
3166, 1981.
Subsequent components of the package
name vary according to an
organization's own internal naming
conventions. Such conventions might
specify that certain directory name
components be division, department,
project, machine, or login names.
Examples:
com.sun.eng
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese
I a large application, you are bound to have two files named exactly the same (java.util.Date and java.sql.Date), especially when you start bringing in third party jars. So basically, you can use packages to ensure uniqueness.
Most importantly, in my opinion, packaging breaks down projects into meaningful segments. So my SQL package has sql-related code, and my logger package handles logging.
In addition to the namespacing mentioned in other answers, you can limit access to methods and fields based on the scope declared on that member.
Members with the public scope are freely accessible, to limit access you normally define them as private (i.e. hidden outside the class).
You can also use the protected scope to limit access to the type and its children.
There is also the default scope (a member with no qualifier has the default scope) which allows child types and types in the same package access to the member. This can be an effective way of sharing fields and methods without making them too widely available, and can help with testing.
For example the method below would be visible to all other members of the same package.
public class Foo {
int doSomething() {
return 1;
}
}
To test the method you could define another type in the same package (but probably a different source location), that type would be able to access the method.
public class FooTest {
#Test
int testDoSomething() {
Foo foo = new Foo();
assertEquals(1, foo.doSomething());
}
}
It allows the program to be composed from multiple different programs/components/libraries, so that their class names will not conflict and the components are easier to organize. See http://java.sun.com/docs/books/tutorial/java/package/index.html
In Java it's customary to name packages as reverse domain names. For example, if your company's domain is "initech.com" and you are making a program called "Gizmo", the package names are typically prefixed "com.initech.gizmo", with subpackages for different components of the program.
Packages are important for giving flexibility of classes separation. They can be used for:
separating projects
separating modules
separating application layers (business, web, dao)
further finer grained code separation
For example
com.mycompany.thisproject.thismodule.web
Could indicate the web layer of some module.
Ultimately, there are 3 core reasons we want to use packages in Java.
1) Easier Maintenance
Organizing classes into packages follows the separation of concerns principle by encapsulation and allows for better cohesion in the overall system design. Moving further, packaging-by-feature allows teams of developers to find relevant classes and interfaces for making changes, supporting vertical-slicing techniques for scaled approaches used in agile methodology. For more information, see blog post: Package your classes by Feature and not by Layers and Coding: Packaging by vertical slice.
2) Provide Package security
Packages allow external access to only public access modifiers on methods in contained classes. Using the protected or no modifier will only be accessible to classes within the same package. For more information, see post:
Which Java access modifier allows a member to be accessed only by the subclasses in other package?
3) Avoid similar naming
Similar to the namespaces of .NET, class names are contained within the scope of their containing package. This means that two mutually exclusive packages can contain classes with the same name. This is because the packages themselves have different names and therefore, the fully qualified names are different. For more information, see tutorial [Naming a Package: The Java Tutorials][3].
From the Wikipedia page on the topic:
"A Java package is a mechanism for organizing Java classes into namespaces similar to the modules of Modula. Java packages can be stored in compressed files called JAR files, allowing classes to download faster as a group rather than one at a time. Programmers also typically use packages to organize classes belonging to the same category or providing similar functionality."
also, if i choose to adopt this, how
should i group them?
This depends largely on the design pattern(s) you will employ in your project. For the most part (particularly, if you're quite new) you'll want to group them by functionality or some other logical similarity.
Other people have provided very Java-specific answers which are fine, but here's an analogy: why do you organize files into directories on your hard drive? Why not just have a flat file system with everything in one directory?
The answer, of course, is that packages provide organization. The part of the program that interfaces with the database is different than the part of the program that displays a UI to the user, so they'll be in different packages.
Like directories, it also provides a way to solve name conflicts. You can have a temp.txt in a couple different directories in the same way that you could have two classes that appear in different packages. This becomes important (1) when you start combining code with other people out there on the internet or (2) even realize how Java's classloading works.
Another important thing about packages is the protected member for access control.
Protected is somewhere between public (everyone can access) and private (only class internal can access). Things marked as protected can be accessed from within the same package or from subclasses. This means that for limited access you don't have to put everything in the same class.
Java is very exact in its implementation. It doesn't really leave room for fudging.
If everyone were to use the same package, they would have to find some "World Wide" way to ensure that no two class names ever collided.
This lets every single class ever written fit into its own "Place" that you don't have to look at if you don't want to.
You may have different "Point" objects defined in 4 different places on your system, but your class will only use the one you expect (because you import that one).
The way they ensure that everyone has their own space is to use your reverse domain, so mine is "tv.kress.bill". I own that domain--Actually I share it with my brother "tv.kress.doug" and even though we share the same domain, we can't have a collision.
If a hundred divisions in your company each develop in Java, they can do so without collision and knowing exactly how to divide it.
Systems that don't do this kind of division seem really flaky to me now. I might use them to hack together a script for something personal, but I'd feel uncomfortable developing anything big without some strict packaging going on.