49

I'm stuck with figuring out a good naming convention for the service layer in a spring application. For each class in the service layer I first write the interface it should implement and then the actual class. So for example I have the following interface:

public interface UserAccountManager{
   public void registerUser(UserAccount newUserAccount);
   public void resetPassword(UserAccount userAccount);
...
}

And then the implementation class...

What bugs me here is UserAccountManager is a good name for the implementation class so I'm forced into giving it a stupid name like SimpleUserAccountManager or UserAccountDbManager. What are some of the conventions you've used so far? Is it a good idea to put the implementation classes in a different package and give them the same names as the interfaces? Also what are your thoughts on using names ending with Manager over names ending with Service?

Vasil
  • 36,468
  • 26
  • 90
  • 114

9 Answers9

67

Here is what we use:

  • XxxDAO (Data Access Object) - Responsible for interacting directly with the EntityManager , JDBC DataSource , file system, etc. Should contain only persistence logic, such as SQL or JPA-QL, but not (or as little as possible) business logic. Should be accessed only from Managers.
  • XxxManager - Manages entites at the business level, usually performs CRUD operations, but adds the required business logic.
  • XxxService - The layer where the business logic resides. Should "speak" in simple objects - Strings, ints, etc. - as much as possible.
  • XxxController - The UI interaction layer. Should speak to Services only.
  • XxxUtilities/XxxUtils - Helper stateless methods, should not depend on any service in the system. If you need such sependency, either convert the utility class to a service or add the service result as a parameter.

For the implementation we add the Impl Suffix (XxxServiceImpl), to distinct it from the interface, and if there are several implementations or we want to add additional information we add it as prefix (JdbcXxxDaoImpl, GoogleMapsGeocodingServiceImpl, etc.). The classes names become a bit long this way, but they are very descriptive and self documenting.

David Rabinowitz
  • 29,904
  • 14
  • 93
  • 125
19

Spring itself gives interfaces generic names and then names the classes based on the details of the implementation. This is one example that comes in mind:

interface: Controller
abstract classes: AbstractController, AbstractCommandController, 
                  SimpleFormController, MultiActionController

I don't think names like SimpleUserAccountManager or UserAccountDbManager are stupid, since they convey some information regarding the implementation of the manager/service.

What I find stupid is the common convention to add the "Impl" suffix at the implementation classes:

my/package/UserAccountManager
my/package/impl/UserAccountManagerImpl

Some people prefer this though.

kgiannakakis
  • 103,016
  • 27
  • 158
  • 194
  • 10
    So would you just call both the interface and the impl UserAccountManager? – Dejell Aug 19 '13 at 14:53
  • 2
    When running tools like jdepend, it is comfortable to separate the code to "interface packages" and "implementation packages". It helps you understand the effects of code changes. – David Rabinowitz Dec 03 '13 at 09:56
  • 1
    @Dejelu, I believe kgiannakakis properly explained with example. Instead of using Impl, we should be using what specific implementation is this for. e.g On DataAccessLayer we can have interface "User", and implementation classes can be suffixed with DataBase API e.g UserDSE(cassandra specific implementation), UserHBASE(HBase specific implementation) etc.. – Rohit Verma Mar 22 '19 at 06:17
  • 1
    @Dejell If you call both the interface and the concrete implementation then at least one of the names is wrong. Either the interface needs a more generic name or the UserAccountManagerImpl needs a more specific name, like AwsUserAccountManager for example. – Caveman Dec 13 '19 at 16:26
11

For the example you give, I would use implementation names that reflect how the class performs the operations, like HibernateUserAccountManager, or JPAUserAccountManager, or JDBCUserAccountManager, etc, or perhaps just UserAccountManagerDAO.

skaffman
  • 398,947
  • 96
  • 818
  • 769
8

It's obviously not important in itself whether class names end in Manager or Service. What's important, generally speaking, is that names accurately convey what is being modeled. And that's the crux of the problem: "Services" or "Managers" aren't real-world objects that we try model in our software objects. Rather, they are places where we collect a bunch of methods that do stuff that simply doesn't fit in with the responsibilities of any of the objects we do need/want to model.

Personally I prefer "service", but only because "manager" seems like something one could actually model, i.e. there could be real-world managers that our "-manager" objects represent. But the point is entirely academical and I immediately concede that it makes no practical difference whatsoever.

What really matters is usually far more basic than such fine points: To have a model that is well understood by all involved in development. If my experience is anything to go by, that is seldom the case. My tip to those asking if "manager" or "service" is the right metaphor is therefore: Flip a coin, make sure everyone knows about the convention, and spend your time pondering and discussing matters that matter!

The Dag
  • 1,811
  • 16
  • 22
  • I like the first paragraph, it conveys a common problem: arbitrary logic that doesn't fit into model classes ends up aggregated in a single class - which is a violation of single responsibility principle, which leads to code coupling. Why not to decouple the logic according to it's meaning into different classes with meaningful names. I'd prefer avoid using Service/Manager suffixes altogether, because for many the temptation to put whatever they have inside 'Service/Manager' class is too high. – Mikhail Selivanov May 18 '17 at 08:14
3

I feel that the Service vs. Manager naming suffix is purely a preference. The only time where "Service" has ever cause confusion for us is when we also have Web services sitting on top of our service layer. On some projects, we simply referred to the Web service classes as brokers as all they did was serve to translate or broker the Web service call into a call to our service tier.

I agree with kgiannakakis that suffixing your implementations with "Impl" is not a good approach. I have also come across coding best practices that mention not to do this. Naming the interface after the abstraction is the generally accepted best practice. Naming the implementation class after the interface with some indicator of its purpose or type, as kgiannakakis suggested, seems to be the generally accepted approach.

When we have Web service based DAOs and ORM based DAOs, we use both packages and class names to differentiate the implementation classes from their interfaces and each other. I think putting the implementations in different packages comes down to how many classes you have in the package, how differently they are implemented, and how much you desire to split things up.

DavidValeri
  • 2,390
  • 15
  • 11
  • That's why I figured Manager would cause less confusion since the frontend for the application is in Flex and there will be AMF services sitting on top of the service layer. Good point. – Vasil Jun 15 '09 at 15:04
3

You could also name the interface IUserAccountManager (this convention is used in Eclipse RCP, for instance) and then use UserAccountManager for the default implementation.

Ilya Boyandin
  • 3,069
  • 25
  • 23
2

To me a service class is about implementing a use case, so I name it according to what kind of user the service is acting on behalf of. So if I have an application with different roles, say Customers, Order Fullfillment people, Data entry people, and Admins, then I'd likely have a CustomerService, an OrderFulfillmentService, a DataEntryService, and an AdminService. I think naming a service according to the kind of data being fetched or twiddled is an anti-pattern. So guessing that UserAccount manipulation would be the domain of an Administrator I would probably call it "AdminService".

Nathan Hughes
  • 94,330
  • 19
  • 181
  • 276
1

Assuming these are for REST services, I think your URI naming convention is more important than the name of the underlying implementation services, since the latter will be largely invisible to clients. Of course you want consistent naming internally, but it is not as crucial.

Some REST guidelines we have used: http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html (my blog)

Andrew Barber
  • 39,603
  • 20
  • 94
  • 123
Robert Morschel
  • 341
  • 3
  • 11
1

Related to the difference between managers and services: I would say use one layer for the business logic (service layer OR manager layer) for as long as possible.

As soon as that layer gets complicated (assume you used services) you can add managers with the responsibility of delegating to one service or another, but keep the business logic inside services.

So I would keep services simple, use managers to manage services, and keep the business logic inside services.

I also agree with avoiding the Impl suffix for implementations and avoiding the I suffix for interfaces. As an example, naming the interface "Controller" and naming the implementation "SimpleController" or "UserController" sounds better for me.

Anghel Contiu
  • 371
  • 2
  • 3