Thursday, May 26, 2016

Best practices to name your JAR file in Java

If you are an author of an internal, proprietary Java library or an external open source library,  or you are one of those lucky developers who ship Java application by yourself then you should follow these best practices while naming your JAR files. These best practices are a result of the practical experience of using hundreds of Java library and application. Following these best practices will help  in better management of JAR files. It's part of my other best practices articles e.g. best practices while naming variable, writing comments, overriding methods, muli-threading, JDBC, and best practices while dealing with passwords. If you are interested in learning more best practices, you can always search those articles on this blog.

You can also take a look at Effective Java, mother of all best practices in Java world and one of the must read books for any Java developer. Joshua Bloch, author of this book has also authored several key classes in JDK e.g. Java Collection Framework and other important classes in java.lang and java.util packages.

JAR file naming best practices in Java

Now let's see some best practices while naming your JAR file:

1) Give them specific name, prefer concrete over abstract
For example, util.jar is the worst jar file name I can think of. All I know is it contains some utility/helper classes. But it is unclear if they belong to an application server, or a framework, or any application sub-systems. You will need to ask someone or refer docs to know what it is. It's part of the DataDirect JDBC Driver distribution. On the other hand, good jar file names are always self-explanatory, for example, struts.jar or spring-mvc.jar

2) Use hyphen (-) instead of underscore (_) as word separator
There are two reasons I advise to prefer hyphen(-) over underscore(_). First, it's easier to type hyphen than underscore; secondly, when the file name is underlined (e.g., in a hyperlink), the _ is invisible. Hyphen has been shunned in file names partly because it is an illegal character in java identifier. But this concern is unwarranted. One of the examples of this best practice is spring-mvc.jar which uses a hyphen to join two words.

3) Append version number if distributed standalone
If your JAR file is distributed standalone then you must append version number on the name of JAR file because they can be dropped into any applications, which may need specific versions. We don't want users to have to compare file size or extract some META-INF files to know its version. Some examples of this best practice are hibernate3.jar, commons-logging-1.0.3.jar, and log4j-1.2.8.jar.

4) Always use extension ".jar", not ".zip"
Theoretically, jar files can have any extension or no extension at all. If you specify it in the system classpath, it should be loadable. The problem is with automatic library detection and loading by containers and frameworks. It's expensive to scan all files so some sort of extension restriction is needed. For this reason, J2EE/JavaEE platform spec requires all library jar files use ".jar" extension, such as WEB-INF/lib/mybeans.jar.

Here is summary of above 4 best practices Java developer should follow while naming their JAR files:

That's all on best practices to name your JAR file in Java. Let me know what are your thoughts about these practices, do you already follow them? Do they make sense? If you are following any other best practices then let us know as well.

Further Reading
  1. Best Practices to name your variable, class, and methods (see here)
  2. Best Practices to follow while overriding methods in Java (see here)
  3. Top 10 Multithreading and Concurrency Best Practices in Java (see here)
  4. Top 10 JDBC Best Practices for Java Programmer (see here)
  5. Best Practices while dealing with passwords in Java (see here)
  6. 10 Best Practices to follow while writing code comments (see here)
  7. 10 Exception handling Best Practices in Java (see here)
  8. Best Practices while writing JUnit tests in Java (see here)
  9. Best Practices to avoid NullPointerException in Java (see here)
  10. Effective Java - Mother of All Best Practices in Java (see here)

Further Learning
Java Fundamentals: The Java Language by Jim Wilson
What's New in Java 8
What's New in Java 9 By Sander Mak

1 comment :

Darin McBride said...

1, 3, and 4, all good ones with huge, vast benefits arising from following those practices. Number 2 is kinda weak. It becomes invisible in a URL when it's underlined in a web page? Really? That's the best reason in favor? That's really quite minor.

Post a Comment