Java 中实用程序类的命名约定

Question

When writing utility classes in Java, what are some good guidelines to follow?

Should packges be "util" or "utils"? Is it ClassUtil or ClassUtils? When is a class a "Helper" or a "Utility"? Utility or Utilities? Or do you use a mixture of them?

The standard Java library uses both Utils and Utilities:

• javax.swing.Utilities
• javax.print.attribute.AttributeSetUtilities
• javax.swing.plaf.basic.BasicGraphicsUtils

Apache uses a variety of Util and Utils, although mostly Utils:

• org.apache.commons.modeler.util.DomUtil
• org.apache.commons.modeler.util.IntrospectionUtils
• org.apache.commons.io.FileSystemUtils
• org.apache.lucene.wordnet.AnalyzerUtil
• org.apache.lucene.util.ArrayUtil
• org.apache.lucene.xmlparser.DOMUtils

Spring uses a lot of Helper and Utils classes:

• org.springframework.web.util.UrlPathHelper
• org.springframework.core.ReflectiveVisitorHelper
• org.springframework.core.NestedExceptionUtils
• org.springframework.util.NumberUtils

So, how do you name your utility classes?

Answer 1

Like many such conventions, what's important is not so much what convention you use, as that you use it consistently. Like, if you have three utility classes and you call them CustomerUtil, ProductUtils, and StoreUtility, other people trying to use your classes are going to constantly get confused and type CustomerUtils by mistake, have to look it up, curse you a few times, etc. (I heard a lecture on consistency once where the speaker put up a slide showing an outline of his speech with three main points, labeled "1", "2nd", and "C".)

Never ever ever make two names that differ only in some subtlety of spelling, like having a CustomerUtil and a CustomerUtility. If there was a good reason to make two classes, then there must be something different about them, and the name should at least give us a clue what that difference is. If one contains utility functions related to name and address and the other contains utility functions related to orders, then call them CustomerNameAndAddressUtil and CustomerOrderUtil or some such. I regularly go nuts when I see meaningless subtle differences in names. Like just yesterday I was working on a program that had three fields for freight costs, named "freight", "freightcost", and "frght". I had to study the code to figure out what the difference between them was.

Answer 2

There is no standard rule/convention in Java world for this. However, I prefer adding "s" at the end of Class name as @colinD has mentioned.

That seems pretty standard to what Master java API Designer Josh Bloch does ( java collection as well as google collection)

As long as Helper and Util goes, I will call something a Helper when it has APIs that help to achieve a specific functionality of a package ( considering a package as to implement a module); mean while a Util may be called in any context.

For example in an application related to bank accounts, all number specific utility static APIs would go to org.mycompany.util.Numbers

All "Account" specific business rule helping APIs would go to

org.mycompany.account.AccountHelper

After all, it is a matter of providing better documentation and cleaner code.

Answer 3

I like the convention of just adding "s" to the type name when the type is an interface or a class you don't control. Examples of that in the JDK include Collections and Executors . It's also the convention used in Google Collections.

When you're dealing with a class you have control over, I'd say utility methods belong on the class itself generally.

Answer 4

I think that 'utils' should be the package name. The class names should specify the purpose of the logic inside it. Adding the sufix -util(s) is redundant.

Answer 5

I'm pretty sure the words "helpers" and "utilities" are used interchangeably. Anyway judging by the examples you provided, I'd say if your classname is an abbreviation (or has abbreviations in it like "DomUtil") then call your package "whatever.WhateverUtil" (or Utils if there's more than one utility in your package). Else if it has a full name instead of an abbreviation, then call it "whatever.WhateverUtilities".

It's really up to you, but so long as coders know what you're talking about, you're good-to-go. If you're doing this professionally as a job for somebody though, ask them what their coding standards are before taking my advice. Always go with the shop standards no matter what as that will help you keep your job. :-)

Answer 6

Here is what I do:

I consider utility classes to be a code smell, but sometimes they are required to reuse methods that do not fit in any other class.

I prefer filename with Utils suffix as it includes various functions for multiple use-cases, I never create a package named utils; instead, I place my utils file within the most suitable existing package for it.

For example, if I need utils for a feature, then I place the MyFeatureUtils.java file within the com.myapp.myfeature package.

If I don't have an appropriate package for the utils file or need to access it from multiple modules then I place it in the root or in common package.

If there is an existing utils package in the project, only then I place the utils class in it.

Some more examples:

• com.myapp.notification.NotificationUtils.java
• com.myapp.account.AccountUtils.java
• com.myapp.data.DatabaseUtils.java
• com.myapp.view.ImageUtils.java
• com.myapp.analytics.LogUtils.java
• src/routes/route-utils.js
• src/middleware/auth-utils.js

PS: I do not use Helper instead of Utils, because helpers can be stateful and generally used within an instance for delegating some states and tasks; whereas utils are completely stateless and should include only static functions.

PS: I do not use Manager instead of Utils, because managers can be stateful and used to provide, manage, and store one or more instances.