Type Design Checklist, Naming

2.2.1. Use a noun or a noun phrase

Details coming soon…

2.2.2. Use PascalCasing

Rationale:

Consistency. This is a long-established Java convention.

2.2.3. Capitalize only the first letter of acronyms

Rationale:

Consistency. PascalCasing is the Java capitalization convention for type names and acronyms should be considered words, not individual letters. This way of capitalizing acronyms is widely used in SDK type names like AclEntry, CipherSpi, Clob, HttpRetryException, or XmlSchema.

That being said, this is one of those cases where the Java SDK itself is inconsistent, a fact best illustrated with the type name HttpURLConnection. For a long time, there was no established Java convention for capitalizing acronyms and each team chose either one or the other. If you judge it based on how many times it appears in SDK names, it looks like all uppercase is the way to go. However, this is not the case. Capitalizing only the first letter is now the Java convention, being used consistently across the newer SDK packages. HttpURLConnection perfectly illustrates the superiority of the mixed case approach: HttpUrlConnection works just fine, HTTPURLConnection is rather hard to read.

Do this:

package com.company.product.api;

public interface HtmlDocument {}
public class XmlConfigurator {}
public class MtomInputStream {}
public class OtdsException {}

Don’t do this:

package com.company.product.api;

public interface HTMLDocument {}
public class XMLConfigurator {}
public class MTOMInputStream {}
public class OTDSException {}

Exceptions:

When adding a new type to an existing package which consistently uses all uppercase acronyms, maintaining the consistency of the package should take precedence. For example, the javax.xml.soap SDK package uses the all uppercase SOAP acronym everywhere in names like SOAPHeader, SOAPElement or SOAPException. If a new type were needed for this package, it should have “SOAP” and not “Soap” in its name.

2.2.4. Use accurate names for purpose of the type

Rationale:

Naming, Behavior and Safety. Callers make a series of assumptions based on type names. For example, if you call a type a Set, callers will assume that it cannot contain duplicate elements. If you call it an Image, they will assume that its content can be represented using popular image formats like JPEG or PNG. Callers will look for a method which returns the amount of money in an Account. If reasonable assumptions about the purpose, use, and behavior of a type are incorrect, the name is inaccurate. Ask people who did not participate in the API design but are familiar with the intended application domain to review your type names for accuracy.

2.2.5. Reserve the shortest, most memorable name for the most frequently used type

Details coming soon…

2.2.6. End the name of all exceptions with the word “Exception”

Rationale:

Consistency. This is a long-established Java convention.

2.2.7. Use singular nouns (Color, not Colors) for naming enumerated types

Rationale:

Consistency. This is a long-established Java convention.

2.2.8. Consider longer names

Rationale:

Naming. Having descriptive names is more important than having short, compact names. Single-word names are nice, but if you cannot find one which accurately describes a type, consider longer composite names. Resist the temptation of using abbreviations. Spell out all the words. Long names are fine in Java.

Do this:

package com.company.product.api;

/**
 * Cluster event raised in a
 * split-brain situation, when network connection
 * between the servers in a cluster is lost, and the servers
 * continue to function forming independent clusters.
 */
public class SplitBrainClusterEvent extends ClusterEvent {}

Don’t do this:

package com.company.product.api;

public class SplitEvent extends ClusterEvent {} //What is a SplitEvent?

Don’t do this:

package com.company.product.api;

public class SbcEvent extends ClusterEvent {} //What is a SbcEvent?

2.2.9. Consider ending the name of derived class with the name of the base class

Details coming soon…

2.2.10. Consider starting the name of an abstract class with the word “Abstract”

Rationale:

Consistency and Naming. Starting the name of abstract classes with the word “Abstract” is an established Java convention with many examples in the Java SDK. However, whether you should start an abstract class name with “Abstract” or not in your API depends on the purpose of the class. If you include abstract classes for callers to extend, you should follow this naming convention, as shown in the first example. However, when you use abstract classes in method signatures (see item 2.1.8.), whether these classes are abstract or not is much less relevant. In such cases, abstract classes should be named like concrete classes or interfaces, without including “Abstract” in the class name, as shown in the second example.

Do this:

package com.company.product.api;

/**
 * Defines method signatures implemented by all authentication
 * handlers.
 */
public interface AuthenticationHandler {}

/**
 * Extend this class to implement your custom authentication handler.
 */
public abstract class AbstractAuthenticationHandler implements AuthenticationHandler {}

Do this:

package com.company.product.api;

/**
 * Defines the common interface and behavior of all
 * triggers.
 */
public abstract class Trigger {}

/**
 * Implements a trigger which fires daily at the specified time
 */
public class DailyTrigger extends Trigger {

    public DailyTrigger(int hour, int minute, int second) {}
}

/**
 * Schedules jobs for execution at a later time
 */
public class Scheduler {

    public void scheduleJob(Job job, Trigger trigger, String description) {}
}

Don’t do this:

package com.company.product.api;

/**
 * Defines the common interface and behavior for all
 * triggers.
 */
public abstract class AbstractTrigger {}

/**
 * Schedules jobs for execution at a later time
 */
public class Scheduler {

    public void scheduleJob(Job job, AbstractTrigger trigger, String description) {}
}

2.2.11. Avoid abbreviations

Details coming soon…

2.2.12. Avoid generic nouns

Details coming soon…

2.2.13. Avoid synonyms

Details coming soon…

2.2.14. Avoid type names used in related APIs

Details coming soon…

2.2.15. Do not use names which differ in case alone

Details coming soon…

2.2.16. Do not use prefixes

Details coming soon…

2.2.17. Do not prefix interface names with “I”

Details coming soon…

2.2.18. Do not use types names used in Java core packages

Rationale:

Naming. Fully qualified Java names (using package names) exist to prevent accidental name collisions, not to encourage intentional reuse of names for unrelated types. It can be especially confusing when a widely recognized name is borrowed from the core Java API, which consists of all packages with names starting with java.* and javax.*. Before using a name, check if it is already used in one of these packages. If it is, find another name for your type.

Don’t do this:

package com.company.product.api;

public class ApiClass extends ContentHandler { //java.net.ContentHandler?

public Container getContainer(){} //java.awt.Container?

public void saveDocument(Document doc) {} //javax.swing.text.Document?

public String readContent() throws ProtocolException {} //java.net.ProtocolException?

public void registerListener(NotificationListener listener) {} //javax.management.NotificationListener?
}

This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 Canada License.