Project Package Organization

the package is a fundamental concept in java — and one of the first things you stumble upon when starting programming in the language. as a beginner, you probably don’t pay much attention to the structure of packages, but as you become a more experienced and mature software developer, you start to think what can be done to improve their efficiency. there are a few major options to consider and picking the right one might not be an obvious choice. this article should give you an overview of commonly selected strategies.

why do we use packages?

from the language perspective, packages in java provide two important features, which are utilized by the compiler. the most apparent one is the namespace definition for classes. several classes with an exactly the same name can be used in a single project as long as they belong to different packages which distinguish one class from another. if you can’t imagine how the language would look like if there were no packages, just have a look at the modularization strategies in the javascript world. before es2015 there were no official standards and a naming collision wasn’t a rare case.

the second thing is that packages allow defining access modifiers for particular members of a project. accessibility of a class, an interface, or one of their members like fields and methods can be limited or completely prohibited for members of different packages.

both features are, first of all, used by the compiler to enforce language rules. for clean coders and software crafters, the primary property of a package is the possibility to have a meaningful name that describes its purpose and the reason for existence. for compilers, it’s just a random string of chars, while for us, it’s another way to express our intention.

what is a package?

in the official java tutorial , we can find the definition, which begins like this:

a package is a namespace that organizes a set of related classes and interfaces. conceptually you can think of packages as being similar to different folders on your computer. you might keep html pages in one folder, images in another, and scripts or applications in yet another. (…)

the first sentence emphasizes the organizational purpose of packages. the definition doesn’t explain, though, what kind of a relationship classes and interfaces should have to consider them as a single group. the question is open to all software developers. recently, kent beck wrote a general piece of advice that also applies to the topic discussed in this post:

if you're ever stuck wondering what to clean up, move similar elements closer together and move different elements further apart

yet, just like the word “related” in the aforementioned package definition, the word “similar” can have completely different meaning to different people. in the remaining part of the article, we will consider possible options in the context of package organization.

package by layer

probably the most commonly recognized similarity between project classes is their responsibility. the approach that uses this property for organization is known as package by layer or horizontal slice and, in practice, looks more or less like on the picture below.

if you didn’t have a chance to work on a project with such a structure, you could come across it in some framework tutorials. for instance, play framework recommended such an approach up to version 2.2. the tutorial of angular.js initially suggested keeping things together based on their responsibilities. the fact they changed their opinion about the subject and updated tutorials should probably excite you to think what the reason was. but before we judge the solution, let’s look at its strengths and weaknesses.

pros

considering layered architecture as the most widely used, it shouldn’t be surprising that developers aim to reflect the chosen architecture in the package structure. the long prevalence of the approach influences the decision to apply the structure in new projects because it’s easier for a team’s newcomers to adapt to an environment that is familiar to them.

finding the right place for a new class in such an application is actually a no-brainer operation. the structure is created at the beginning of development and kept untouched during the entire project’s existence. the simplicity allows keeping the project in order, even by less-experienced developers , as the structure is easily understandable.

cons

some people say having all model classes in one place makes them easier to reuse because they can simply be copied with the whole package to another project. but is it really the case? the shape of a particular domain model is usually valid only in a bounded context within a project. for instance, the product class will have different properties in a shopping application than in an application that manages orders from manufacturers. and even if you would like to use the same classes, it would be reasonable to extract them to a separate jar marked as a dependency in each application. duplication of code leads to bugs, even if it exists in separate-but-related projects, hence we should avoid copy-pasting.

a major disadvantage of the package by layer approach is overuse of the public access modifier. modern ides create classes and methods with the public modifier by default without forcing a developer to consider a better-fitting option. in fact, in the layered package organization, there is no other choice. exposing a repository just to a single service class requires the repository to be public. as a side effect, the repository is accessible to all other classes in the project, even from layers that shouldn’t directly communicate with it. such an approach encourages creating unmaintainable spaghetti code and results in high coupling between packages.

while jumping between connected classes in ides is nowadays rather simple no matter where they are located, adding a new set of classes for a new feature required more attention. it is also harder to assess the complexity of a feature just by looking at code as classes are spread across multiple directories.

at the beginning, we said that the name of a package should provide additional details about its content. in the package by layer approach, all packages describe the architecture of the solution, but, separately, they don’t give any useful information. actually, in many cases, they duplicate information present in class names of its members.

package by feature

on the other side of the coin, you can structure your classes around features or domain models. you might have heard of this approach as the vertical slice organization. if you work only with the horizontal slice, at the first glance, it might look a little bit messy. but in the end, it’s just a question of mindset. the following picture represents the same classes as in the previous paragraph, but with a different package layout.

you probably don’t keep all your left shoes in one place and all right in another just because they fit the same feet. you keep your shoes in pairs because that’s the way you use them. by the same token, you can look at the classes in your project. the core idea of the vertical slice is to place all classes that build a particular feature in a single package. by following this rule, in return, you will receive some benefits but also face some negative consequences.

pros

when all feature classes are in a single package, the public access modifier is much more expressive, as it allows describing what part of a feature should be accessible by other parts of the application. within a package, you should favor usage of the package-private modifier to improve modularization. it’s a good idea to modify default templates in your ide to avoid creating public classes and methods. making something public should be a conscious decision. fewer connections between classes from different packages will lead to cleaner and a more maintainable code base.

in the horizontal slice, packages have the same set of names in each project while, in the vertical slice approach, packages have much more meaningful names describing their functional purpose . just by looking at the project structure, you can probably guess what users can do with the application. the approach also expresses hierarchical connections between features. aggregate roots of the domain can be easily identified, as they exist at the lowest level of the package tree. the package structure documents the application.

grouping classes based on features results in smaller and easier-to-navigate packages. in the horizontal approach, each new feature increases the total number of classes in layer packages and makes them harder to browse. finding interesting elements in the long list of classes becomes an inefficient activity. by contrast, a package focused on a feature grows only if that feature is extended . a new feature receives its own package in an appropriate node of the tree.

it’s also worth mentioning the flexibility of the vertical slice packaging. with the growing popularity of the microservice architecture, having a monolith application that is already sliced by features is definitely much easier to convert into separate services than a project that organizes classes by layers. adopting the package by feature approach prepares your application for scalable growth.

cons

along with the development of the project, the structure of packages requires more care. it’s important to understand that the package tree evolves over time as the application gets more complex. from time to time, you will have to stop for a while and consider moving a package to a different node or to split it into smaller ones. the clarity of the structure doesn’t come for free. the team is responsible for keeping it a good shape with alignment to knowledge about the domain.

understanding the domain is the key element of clean project structure. choosing a right place for a new feature may be problematic, especially for team newcomers, as it requires knowledge about the business behind your application. some people may consider this as an advantage, as the approach encourages sharing knowledge among team members. the introduction of a new developer to the project is slightly more time consuming, yet it might be seen as an investment.

mixed approach

you may think that no extremity is good. can’t we just take what is best from both approaches and create a new quality that is intermediate between two extremes? there are two possible combinations. either the first level of packages is divided by layer and features are their children, or features build the top level and layers are their sub-nodes.

the first option is something that you might have encountered, as it is a common solution for packages that grow to large sizes. it increases the clarity of the structure, but unfortunately, all disadvantages of the package by layer approach apply just like before. the greatest problem is that the public modifier must still be used almost everywhere in order to connect your classes and interfaces.

with the other option, we should ask the question of whether the solution really makes much sense. the package by feature approach supports organization of layers, but it does it on the class level and not using packages . by introducing additional levels of packages, we lose the ability to leverage default access modifiers. we also don’t gain much simplicity in the structure. if a feature package grows to an unmanageable size, it’s probably better to extract a sub-feature.

summary

picking the package structure is one of the first choices you have to make when starting a new project. the decision has an impact on the future maintainability of the whole solution. although, in theory, you can change the approach at any point in time, usually the overall cost of such a shift simply prevents it from happening. that is why it’s particularly important to spend a few minutes with your whole team at the beginning and compare possible options. once you make a choice, all you have to do is to make sure that every developer follows the same strategy. it might be harder for the package by feature approach, especially if done for the first time, but the list of benefits is definitely worth the effort.

if you have any experience with the vertical slice and would like to add your two cents to the topic, don’t hesitate to share your thoughts in the comments . also, please consider sharing the post with your colleagues. it would be great to read the outcome of your discussions and feelings about the approach.