Category: Java

Naming Conventions: Java Packages

Posted on by Eric F. Savage

When developing, conventions can mean the difference between producing something clear and concise and producing something confusing and arcane. They exist at all levels, from the industry and the language down to specific modules of applications. I’m going to attempt to codify some conventions for aspects I use heavily, and I’ll start with one of the easier ones, Java package names. Sun has some basic ones, but I think some more specific guidelines are warranted.

  1. Names should be all lowercase. Uppercase and mixed case denote other concepts in Java and there’s no need to muddy the waters further.
  2. Names should be alphanumeric, preferably just alphabetical.
  3. Do not use version numbers or dates (see below for a possible exception).
  4. Use tld.domain-you-own.project/library.* for distributed or published code. This follows with Sun’s convention, and is the only way to know a name is globally unique, or at least that you are the one that’s allowed to use it.
  5. Do not use tld.domain-you-own.* for internal code that should not be distributed. I typically just use the project or library’s name as the first segment. This convention can be useful in signaling other developers that code is for internal use only, and if something is converted from internal to external usage, this will help identify which version an application was built against.
  6. Package names that are nouns should be singular (mycompany.myproject.account). This maintains consistency with packages that are named for actions (mycompany.myproject.search) and adjectives (mycompany.myproject.common).
  7. Store DAOs in a “data” subpackage. This helps the tree-views in IDEs and also allows for easier control of logging. If you’re being formal and encapsulate DAO operations in a manager class, the manager class should not be in the data package because it’s grammar is business-based, not persistence-based.
  8. Classes that are heavily dependent on third-party packages should be in a subpackage named for the primary dependency. A Hibernate implementation of your DAO should live in mycompany.myproject.data.hibernate. This helps greatly with logging configuration. This is one place where version numbers are permissible, such as mycompany.myproject.data.hibernate3. Use this exception very sparingly, as it can be confusing with regards to forward compatibility.
  9. Classes that are extensions of third-party code should be named for the dependency and be outside of the project’s or product’s context. For example, if you are creating a new type of controller for Spring MVC that does not depend on project-specific code, put it in mycompany.spring.controller. If it is integrated with the application, see the previous point.
  10. Don’t expose organizational details in the package structure (mycompany.mydepartment.myproject). Naming packages by department, office, or region will surely be confusing soon due to management’s penchant to reorganize and reassign.

I consider the above a work in-progress, and welcome comments.

The Toolbox: Introduction & Log4J

Posted on by Eric F. Savage

In my own semantics, software development is a blend between a conventional profession and a craft. As a craftsman, I have a preferred set of tools with which I build and create. Of course, as a contract developer, I don’t always get to use what I want, but these days I more often find myself in a position to do so. I figure it might be useful to others, especially those just getting into the game, to see what an experienced developer actually uses, and why. So let’s start with an easy one, Log4J.


Log4J.There are essentially 3 major choices when it comes to logging in Java. Log4J, Commons Logging, and Java Logging. My current preference is Log4J. Why?

Commons Logging is an abstraction layer, and defaults to using Log4J for its actual logging. The main idea behind CL is that you aren’t tied to a specific logger. I think CL is flawed in two ways:

1. Log4J is itself extensible. Writing a custom appender (the piece that actually writes the log message) is a fairly trivial task, and if your project makes such a fundamental shift as to change its logging API, writing a bridge appender is a negligible amount of effort. So if you’re going to be using Log4J anyways, as most projects do, why add unnecessary complexity?
2. Commons Logging is always more difficult to configure. I honestly can’t figure out why, but almost every project I’ve worked on that uses CL has had issues, especially when you have a mix of libraries which do or do not use it.

Java Logging, added several years ago in Java 1.4, was supposed to eliminate the need for third party logging APIs. It was, and remains, a good idea, but it does not make a compelling case to switch from the vastly more popular Log4J. Last time I checked, the standard logging API was missing a rolling file appender, which is essential for any production environment. It is also slightly less flexible to configure, but the main reason it has largely been irrelevant is that it doesn’t offer anything that Log4J does not.

What would make me switch?

I’m a very heavy logger. I will often write code with as many log statements as regular lines of code, and of course most of these statements are debug/trace level. The problem this introduces is performance. Let’s look at this example:

Person person = PersonFactory.getPerson(name);
log.debug("Found " + person.getName());
precinct.register(person);

The problem is that even if logging is at a level above debug, getName() will be invoked. In practice these statements rarely do anything expensive, but it can be the proverbial death by a thousand cuts. The Log4J way to avoid this is to do the following:

Person person = PersonFactory.getPerson(name);
if(log.isDebugEnabled()) {
log.debug("Found " + person.getName());
}
precinct.register(person);

Messy huh? What I would like to see is the ability for the java compiler to skip these statements entirely, without the cruft currently required. If this ended up being some special case that required the use of the standard logging API, I would switch. The slick way to do this would be to have the ability to annotate methods for lazy reads of parameters being passed to them, but that, as Alton Brown would say, is another show.