Are there best practices for (Java) package organisation?

Question

A little while ago, I saw a question answered here regarding the fine-grained organisation of java packages. For example, my.project.util, my.project.factory, my.project.service etc.

I can't find it now, so I may as well ask the question.

Are there best practices with regards to the organisation of packages in Java and what goes in them?

How do you organise your classes in your Java project?

For instance, a project I'm working on with a few people has a package called beans. It started out being a project containing simple beans, but has ended up (through poor experience and lack of time) contiaining everything (almost). I've cleaned them up a little, by putting some factory classes in a factory package (classes with static methods that create beans) but we have other classes that do business logic and others that do simple processing (not with business logic) like retrieving a message for a code from a properties file.

Your thoughts and comments are appreciated.

Answer 1

I'm not aware of standard practices for package organization. I generally create packages that cover some reasonably broad spectrum, but I can differentiate within a project. For example, a personal project I'm currently working on has a package devoted to my customized UI controls (full of classes subclassing swing classes). I've got a package devoted to my database management stuff, I've got a package for a set of listeners/events that I've created, and so on.

On the other hand I've had a coworker create a new package for almost everything he did. Each different MVC he wanted got its own package, and it seemed a MVC set was the only grouping of classes allowed to be in the same package. I recall at one point he had 5 different packages that each had a single class in them. I think his method is a little bit on the extreme (and the team forced him to reduce his package count when we simply couldn't handle it), but for a nontrivial application, so would putting everything in the same package. It's a balance point you and your teammates have to find for yourself.

One thing you can do is try to step back and think: if you were a new member introduced to the project, or your project was released as open source or an API, how easy/difficult would it be to find what you want? Because for me, that's what I really want out of packages: organization. Similar to how I store files in folder on my computer, I expect to be able to find them again without having to search my entire drive. I excpect to be able to find the class I want without having to search the list of all classes in the package.

Answer 2

Package organization or package structuring is usually a heated discussion. Below are the simple guidelines for package naming and structuring:

• Follow java package naming conventions
• Structure your packages according to their functional role as well as their business role
  • Break down your packages according to their functionality or modules. e.g. com.company.product.modulea
  • Further break down could be based on layers in your software. But don't go overboard if you have very less classes in the package, then it makes sense to have everything in the package. e.g. com.company.product.modue.web or com.company.product.modue.util etc.
  • Avoid going overboard with structuring, IMO avoid separate packaging for exceptions, factories, etc. unless there's a pressing need.
• If your project is small, keep it simple with few packages. e.g. com.company.product.model and com.company.product.util, etc.
• Take a look at some of the popular open soruce projects out there on apache. See how they use structuring, for various sized projects.
• Also consider build and distribution when naming ( allowing you to distribute your api or SDK in a different package, see servlet api)

After a few experiments and trials you should be able to come up with a structuring that you are comfortable with. But don't be fixated on one convention, be open to changes.

-cheers

Answer 3

Usually you put classes that share a common inheritance hierarchy into the same package. If you have support classes like factories you put them in the same package as well, but if these factories for example share a common inheritance hierarchy again you put them into a subpackage.

Answer 4

I organize packages by feature, not by patterns or implementation roles. I think packages like:

• beans
• factories
• collections

are wrong. I prefer, for example:

• orders
• store
• reports

so i can hide implementation details through package visibility: factory of orders should be in the orders package so details about how to create an order are hidden.

Answer 5

Are there best practices with regards to the organisation of packages in Java and what goes in them?

Not really no. There are lots of ideas, and lots opinions, but "best practice" is to use your common sense!

However, there is one principal that probably has broad acceptance. Your package structure should reflect your application's (informal) module structure, and you should aim to minimize (or ideally entirely avoid) any cyclic dependencies between modules.

(Cyclic dependencies between classes in a package / module are just fine, but inter-package cycles tend to make it hard understand your application's architecture, and can be a barrier to code reuse.)

Answer 6

I usually organize by layers, because I write a lot of web apps. So I'll have persistence, service, model, view, util, etc.