How to use the Java API design checklist

This before-and-after example illustrates how to use the Java API design checklist. We borrowed the original API from the free online eBook “OSGi in Practice” by Neil Bartlett. The author uses the API through the book to illustrate various OSGi features and considers it a “reasonable attempt” at defining an API.

Here is the description of the API strait from the book:

“Thanks to the internet, we are today bombarded by messages of many kinds. Email is an obvious example, but also there are the blogs that we subscribe to through RSS or ATOM feeds; SMS text messages; “microblogging” sites such as Twitter[?] or Jaiku[?]; IM systems such as AOL, MSN or IRC; and perhaps for professionals in certain fields, Reuters or Bloomberg newswire feeds and market updates. Sadly we still need to flip between several different applications to view and respond to these messages. Also there is no coherent way to apply rules and automated processing to all of our inbound messages. For example, I would like a way to apply my spam filters, which do a reasonable job for my email, to my SMS text messages, as spam is increasingly a problem in that medium.”

“To support multiple kinds of message sources, we need to build an abstraction over messages and mailboxes, so a good place to start is to think about what those abstractions should look like. In Java we would represent them as interfaces. Listing 1 contains a reasonable attempt to define a message in the most general way.”

“Objects implementing this interface are really just message headers. The body of the message could be of any type: text, image, video, etc. We need the header object to tell us what type the body data is, and how to access it.”

“Next we need a way to retrieve messages. The interface for a mailbox could look like Listing 2. We need a unique identifier to refer to each message, so we assume that an ID of type long can be generated or assigned by the mailbox implementation. We also assume that the mailbox maintains some temporal ordering of messages, and is capable of telling us about all the new messages available given the ID of the most recent message known about by the reader tool. In this way the tool can notify us only of new messages, rather than ones that we have already read.”

“Many back-end message sources, such as the IMAP protocol for retrieving email, support storing the read/unread state of a message on the server, allowing that state to be synchronized across multiple clients. So, our reader tool needs to notify the mailbox when a message has been read. In other protocols where the back-end message source does not support the read/unread status, this notification can be simply ignored.”

“Finally we need the code for the exceptions that might be thrown. These are shown in Listing 3 and Listing 4.”

Design review

The API design shown below is fairly typical for a first draft. All major functional requirements are met, but there are some remaining design issues. We will do a design review using the Java API design checklist to remember overlooked design requirements, spot mistakes, identify less-than-optimal design choices and opportunities for improvements. We marked the identified issues with “//see …” comments in the listings below. The hyperlinks point to the relevant checklist items in the list.

Listing 1: The original Message (see after)

1   package org.osgi.book.reader.api;  //see 1.2.7, 1.3.1

3   import java.io.InputStream;

5   public interface Message{ //see 2.1.8, 2.2.18, 2.4.1, 2.7.1

7   /**
8   * @return The unique (within this message’s mailbox) message ID. //see 3.9.3
9   */
10  public long getId();

12  /**
13  * @return A human-readable text summary of the message. In some
14  * messaging systems this would map to the "subject" field. //see 3.9.3
15  */
16  public String getSummary();

18  /**
19  * @return The Internet MIME type of the message content. //see 3.9.3
20  */
21  public String getMIMEType(); //see 2.2.3

23  /**
24  * Access the content of the message.
25  *
26  * @throws MessageReaderException
27  */
28  public InputStream getContent() throws MessageReaderException; //see 2.1.3, 3.2.3, 3.4.2

30  }

Listing 2: The original Mailbox (see after)

1   package org.osgi.book.reader.api;

3   public interface Mailbox{ //see 2.1.8, 2.4.1, 2.7.1

5   public static final String NAME_PROPERTY = "mailboxName";

7   /**
8   * Retrieve all messages available in the mailbox.
9   *
10  * @return An array of message IDs.
11  * @throws MailboxException
12  */
13  public long[] getAllMessages() throws MailboxException; //see 3.1.3, 3.2.3, 3.3.8, 3.4.2

15  /**
16  * Retrieve all messages received after the specified message.
17  *
18  * @param id The message ID.
19  * @return An array of message IDs.
20  * @throws MailboxException
21  */
22  public long[] getMessagesSince(long id) throws MailboxException; //see 3.1.3, 3.2.3, 3.3.1, 3.3.8, 3.4.2

24  /**
25  * Mark the specified messages as read/unread on the back-end
26  * messagesource, where supported,e.g.IMAP supports this
27  * feature.
28  *
29  * @param read Whether the specified messages have been read.
30  * @param ids An array of messageIDs.
31  * @throwsMailboxException
32  */
33  public void markRead(boolean read, long[] ids) throws MailboxException; //see 3.1.14, 3.3.25

35  /**
36  * Retrieve the specified messages.
37  *
38  * @param ids The IDs of the messages to be retrieved.
39  * @return Anarray of Messages.
40  * @throws MailboxException
41  */
42  public Message[] getMessages(long[] ids) throws MailboxException; //see 3.1.3, 3.2.3, 3.3.1, 3.3.8, 3.4.2

44  }

Listing 3: The original MessageReaderException (see after)

1   package org.osgi.book.reader.api;

3   public class MessageReaderException extends Exception{ //see 2.1.3, 2.6.2

5   private static final long serialVersionUID = 1L; //see 2.3.2

7   public MessageReaderException(String message) {
8      super(message);
9   }

11  public MessageReaderException(Throwable cause){
12     super(cause);
13  }

15  public MessageReaderException(String message,Throwable cause){
16     super(message,cause);
17  }

19  }

Listing 4: The original MailboxException (see after)

1   package org.osgi.book.reader.api;

3   public class MailboxException extends Exception{ //see 3.4.2, 2.7.1

5   private static final long serialVersionUID = 1L; //see 2.3.2

7   public MailboxException(String message) {
8      super(message);
9   }

11  public MailboxException(Throwable cause){
12     super(cause);
13  }

15  public MailboxException(String message,Throwable cause){
16     super(message,cause);
17  }

19  }

Redesign

Our design review highlighted several omissions, issues, and inconsistencies. Listings 5 6, 7, 8 and 9 show the redesigned API. During the redesign we had many tradeoffs to consider. In addition to the checklist items identified during the design review we considered several others. We show these additional checklist items within square brackets inside comments and using the //also … comments in code. The hyperlinks point to the relevant checklist items in the list.

Listing 5: package overview (package-info.java) for the redesigned API

1   /**
2   * <p>
3   * Provides simple and generic read-only access to messages from a variety
4   * of different sources like email, RSS and Atompub feeds, instant messaging
5   * services, Facebook, SMS and Twitter.</p> [1.3.3]
6   * <p>
7   * All concrete classes implement either {@link org.osgi.book.reader.MessageHeader}
8   * or {@link org.osgi.book.reader.Mailbox}. Together, these two abstract classes define the
9   * generic interface used in the package. All concrete classes are protocol-specific
10  * implementations and extensions like {@link org.osgi.book.reader.EmailHeader} or
11  * {@link org.osgi.book.reader.ImapMailbox}</p> [1.3.5]
12  * <p>
13  * Classes from this package are not intended for direct instantiation.
14  * They have no public constructors. Instead, pre-configured instances of mailboxes
15  * must be retrieved by their name through a JNDI lookup from the naming context
16  * "com/env/mailboxes"</p>
17  * <p>
18  * Classes from this package are not intended for extension. All concrete
19  * classes are final and abstract classes have no public or protected constructors.</p>
20  * <p>
21  * The code sample bellow shows how to read and print out messages
22  * from all configured mailboxes: </p> [1.3.6]
23  *
24  * <pre>
25  *     import org.osgi.book.reader.*;
26  *     import javax.naming.*;
27  *     import java.rmi.RemoteException;
28  *
29  *     try {
30  *         Context initialContext = new InitialContext();
31  *         NamingEnumeration mailboxNames = initialContext.list("com/env/mailboxes");
32  *         while(mailboxNames.hasMore())
33  *         {
34  *             NameClassPair pair = (NameClassPair) mailboxNames.next();
35  *             Mailbox<?> mailbox = (Mailbox<?>) initialContext.lookup(pair.getName());
36  *             for(MessageHeader h : mailbox.readAllMessageHeaders()) {
37  *                  System.out.println(h);
38  *             }
39  *         }
40  *     } catch (NamingException e) {
41  *         e.printStackTrace();
42  *     } catch (RemoteException e) {
43  *         e.printStackTrace();
44  *     }
45  * </pre>
46  *
47  * @version 2.0 [1.3.10]
48  *
49  * <br/>
50  * <p>This sample API is an adaptation of the original published in
51  * <a href="http://njbartlett.name/osgibook.html">"OSGi in Practice"</a> by Neil Bartlett
52  *
53  * <br/>
54  * <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
55  * <img alt="Creative Commons License" style="border-width:0"
56  * src="http://i.creativecommons.org/l/by-sa/3.0/88x31.png" /></a>
57  *
58  * <br/>
59  * Sample API by Neil Bartlett and Ferenc Mihaly is licensed under a
60  * <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
61  * Creative Commons Attribution-ShareAlike 3.0 Unported License</a>. [1.3.12]
62  */
63
64  package org.osgi.book.reader;

Listing 6: Message(Header) after redesign (see before)

1   package org.osgi.book.reader;  

3   import java.io.InputStream;
3a  import java.io.Serializable;
3b  import java.rmi.RemoteException;

4a  /**
4b  * Contains descriptive (structured) information about a message and
4c  * defines methods for retrieving the (unstructured) message body. [2.7.3]
4d  * Read-only (immutable) instances of this abstract type are
4e  * read from a Mailbox implementation. [2.7.5]
4f  * Concrete derived types may offer additional information or functionality, like {@link EmailHeader}. [2.3.4]
4g  * The natural ordering is the order of reception.
4h  * For a code sample, see {@link Mailbox}.. [2.7.6, 2.7.9]
4i  */
5   public abstract class MessageHeader implements Comparable, Serializable { //also 2.2.4, 2.2.8, 2.2.10, 2.3.11, 2.3.12, 2.3.17

6a  MessageHeader() {} //also 2.3.9, 2.3.21

6b  @Override
6c  public boolean equals(Object obj) {...}
6d  @Override
6e  public int hashCode() {...}
6f  @Override
6g  public String toString() {...}
6h  @Override
6i  public int compareTo(Object o) {...} //also 2.3.10, 2.3.11

7   /**
7a  * Returns the unique (within this message’s mailbox) message ID.
8   * @return The message ID.
9   */
10  public long getId() {...}

12  /**
12a * Returns a human-readable text summary of the message.
13  * @return A human-readable text summary of the message. In some
14  * messaging systems this would map to the "subject" field. Not null.
15  */
16  public String getSummary() {...}

18  /**
18a * Returns the Internet MIME type of the message content.
19  * @return The Internet MIME type of the message content. Not null.
20  */
21  public String getMimeType() {...}

23  /**
24  * Access the content of the message from the remote mailbox. [item 3.9.14]
25  *
25a * @return An input stream for reading the message content. Not null.
26  * @throws RemoteException In case of a communication error with a remote mailbox
26  * @throws MailboxException Unrecoverable internal mailbox error
27  */
28  public abstract InputStream streamContent() throws RemoteException, MailboxException;

30  }

Listing 7: Mailbox after redesign (see before)

1   package org.osgi.book.reader;
1a
1b  import java.rmi.RemoteException;
1c  import java.util.Collection;
1c  import java.util.SortedSet;

2a  /**
2b  * Represents a generic and abstract mailbox interface for accessing incoming messages. [2.7.3]
2c  * Several implementations based on various messaging protocols (POP3, IMAP, RSS, etc.) are available.
2d  * Configured instances of mailboxes are retrieved by performing a JNDI lookup. [2.7.5]
2e  * The code sample below prints out the summary of all messages from the default mailbox. [2.7.6]
2f  * <pre>
2g  *     Context context = new InitialContext();
2h  *     Mailbox<?> mb = (Mailbox<?>) context.lookup("com/env/mailbox/default");
2i  *     for(MessageHeader h : mb.readAllMessageHeaders()) {
2j  *         System.out.println(h); //uses toString()
2k  *     }
2l  * </pre>
2m  */
3   public abstract class Mailbox<T extends MessageHeader> implements Comparable {//also 2.1.10, 2.3.11

5   public static final String NAME_PROPERTY = "mailboxName";

6a  Mailbox() {...} //also 2.3.9, 2.3.21

6b  @Override
6c  public boolean equals(Object obj) {...}
6d  @Override
6e  public int hashCode() {...}
6f  @Override
6g  public String toString() {...}
6h  @Override
6i  public int compareTo(Object o) {...} //also 2.3.10, 2.3.11

7   /**
8   * Retrieve all messages available in the mailbox.
9   *
10  * @return The ordered set of all available message headers. Not null.
10a * @throws RemoteException In case of a communication error with a remote mailbox
11  * @throws MailboxException Unrecoverable internal mailbox error
12  */
13  public abstract SortedSet<T> readAllMessageHeaders()
13a                              throws RemoteException, MailboxException; //also 3.1.3, 3.1.9, 3.3.9

15  /**
16  * Retrieve all messages received after the specified message.
17  *
18  * @param last The last read message header; not null.
19  * @return The ordered set of message headers since the lst read message header. Not null.
19a * @throws NullPointerException If parameter is null
19b * @throws RemoteException In case of a communication error with a remote mailbox
20  * @throws MailboxException Unrecoverable internal mailbox error
21  */
22  public abstract SortedSet<T> readMessageHeadersSince(T last)
22a     throws NullPointerException, RemoteException, MailboxException; //also 3.1.3, 3.1.9, 3.3.9, 3.4.6, 3.4.12

24  /**
25  * Mark the specified messages as read on the back-end
26  * messagesource, where supported,e.g.IMAP supports this
27  * feature.
28  *
29  * @param headers The list of message headers to be marked; not null.
29a * @throws NullPointerException If parameter is null
29b * @throws RemoteException In case of a communication error with a remote mailbox
31  * @throws MailboxException Unrecoverable internal mailbox error
32  */
33  public abstract void markRead(Collection<T> headers)
33a     throws NullPointerException, RemoteException, MailboxException; //also 3.1.3, 3.1.9, 3.1.10, 3.3.9, 3.4.6, 3.4.12
33b public abstract void markRead(T header)
33c     throws NullPointerException, RemoteException, MailboxException; //also 3.1.3

34a /**
34b * Mark the specified messages as unread on the back-end
34c * messagesource, where supported,e.g.IMAP supports this
34d * feature.
34e *
34f * @param headers The list of message headers to be marked
29g * @throws NullPointerException If parameter is null
34h * @throws RemoteException In case of a communication error with a remote mailbox
34i * @throws MailboxException Unrecoverable internal mailbox error
34j */
34k public abstract void markUnread(Collection<T> headers)
34l     throws NullPointerException, RemoteException, MailboxException; //also 3.1.3, 3.1.9, 3.3.9, 3.1.10, 3.4.6, 3.4.12
34m public abstract void markUnread(T header)
34n     throws NullPointerException, RemoteException, MailboxException; //also 3.1.3

Listing 8: MessageReaderException after redesign (see before)

(no longer needed)

1   package org.osgi.book.reader;

3   public class MessageReaderException extends Exception{

5   private static final long serialVersionUID = 1L;

7   public MessageReaderException(String message) {
8      super(message);
9   }

11  public MessageReaderException(Throwable cause){
12     super(cause);
13  }

15  public MessageReaderException(String message,Throwable cause){
16     super(message,cause);
17  }

19  }

Listing 9: MailboxException after redesign (see before)

1   package org.osgi.book.reader;

2a  /**
2b  * Signals an unrecoverable internal mailbox error.
2c  */
3   public class MailboxException extends RuntimeException{

5    

7   public MailboxException(String message) {
8      super(message);
9   }

11  public MailboxException(Throwable cause){
12    super(cause);
13  }

15  public MailboxException(String message,Throwable cause){
16     super(message,cause);
17  }

18a /* IMPLEMENTATION STUFF */
18b private static final long serialVersionUID = 1L;
18c
19  }

Discussion

Is the redesigned version better than the original? This is a tricky question, a bit like asking which car is better or which city is more pleasant to live in. Your answer will depend on what aspects you consider important. There is no doubt that we managed to improve many aspects of the API. The new version is noticeably more consistent, safer to use, and better documented. Listing 10 shows the code we wrote to aggregate massages from several mailboxes before and after the redesign. Regardless of your stance on the arrays versus collections debate (some developers dislike generic Java collections, finding them too verbose), you’ll probably agree that the second version is safer to use.

Listing 10: Code for aggregating messages before and after the redesign

1  /**
2  * Before
3  */
4  public static Message[]
5  getAllMessages(Mailbox[] mailboxes) throws MailboxException {
6  	Message[] result = new Message[0];
7  	for (Mailbox mailbox : mailboxes) {
8  		Message[] messages = mailbox.getMessages(mailbox.getAllMessages());
9  		result = Arrays.copyOf(result, result.length + messages.length);
10 		System.arraycopy(messages, 0, result, result.length, messages.length);
11 	}
12 	return result;
13 }

1  /**
2  * After
3  */
4  public static SortedSet<MessageHeader>
5  readAllMessageHeaders(Set<Mailbox<?>> mailboxes) throws RemoteException {
6  	SortedSet<MessageHeader> result = new TreeSet<MessageHeader>();
7  	for(Mailbox<?> mailbox : mailboxes) {
8  		result.addAll(mailbox.readAllMessageHeaders());
9  	}
10 	return result;
11 }

This being said, some of our design choices are not the best. For example, we choose JNDI lookup over public constructors to illustrate the importance of proper documentation, not because we don’t recommend constructors. We used generic abstract classes to illustrate how to improve API safety with strong compile time type checks, intentionally disregarding that some developers may be uncomfortable with Java generics.

This brings us to an important point: the API design checklist is just one of the tools we use for API design and checklist items should not be applied mechanically, without thinking. This is especially true for checklist items introduced with the words Favor, Consider, and Avoid. Considering the perspective of the caller and focusing on improving the main use cases should help decide what design trade-offs to make.

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

Java API Design Checklist

There are many different rules and tradeoffs to consider during Java API design. Like any complex task, it tests the limits of our attention and memory. Similar to the pilots’ pre-flight checklist, this list helps software designers remember obvious and not so obvious rules while designing Java APIs. It is a complement to and intended to be used together with the API Design Guidelines.

We also have some before-and-after code examples to show how this list can help you remember overlooked design requirements, spot mistakes, identify less-than-optimal design choices and opportunities for improvements.

Click the [explain] link next to a checklist item (where available) for details about the rationale, examples, design tradeoffs or other limitations of applicability.

This list uses the following conventions:

   (Do) verb...  - Indicates the required design
    Favor...     - Indicates the best of several design alternatives
    Consider...  - Indicates a possible design improvement
    Avoid...     - Indicates a design weakness
    Do not...    - Indicates a design mistake

1. Package Design Checklist

1.1. General

  • 1.1.1. Favor placing API and implementation into separate packages [explain]
  • 1.1.2. Favor placing APIs into high-level packages and implementation into lower-level packages [explain]
  • 1.1.3. Consider breaking up large APIs into several packages [explain]
  • 1.1.4. Consider putting API and implementation packages into separate Java archives [explain]
  • 1.1.5. Avoid (minimize) internal dependencies on implementation classes in APIs [explain]
  • 1.1.6. Avoid unnecessary API fragmentation [explain]
  • 1.1.7. Do not place public implementation classes in the API package [explain]
  • 1.1.8. Do not create dependencies between callers and implementation classes [explain]
  • 1.1.9. Do not place unrelated APIs into the same package [explain]
  • 1.1.10. Do not place API and SPI into the same package [explain]
  • 1.1.11. Do not move or rename the package of an already released public API [explain]

1.2. Naming

  • 1.2.1. Start package names with the company’s official root namespace [explain]
  • 1.2.2. Use a stable product or product family name at the second level of the package name [explain]
  • 1.2.3. Use the name of the API as the final part of the package name [explain]
  • 1.2.4. Consider marking implementation-only packages by including “internal” in the package name [explain]
  • 1.2.5. Avoid composite names [explain]
  • 1.2.6. Avoid using the same name for both package and class inside the package [explain]
  • 1.2.7. Avoid using “api” in package names [explain]
  • 1.2.8. Do not use marketing, project, organizational unit or geographic location names [explain]
  • 1.2.9. Do not use uppercase characters in package names [explain]

1.3. Documentation

  • 1.3.1. Provide a package overview (package.html) for each package [explain]
  • 1.3.2. Follow standard Javadoc conventions [explain]
  • 1.3.3. Begin with a short, one sentence summary of the API [explain]
  • 1.3.4. Provide enough details to help deciding if and how to use the API [explain]
  • 1.3.5. Indicate the entry points (main classes or methods) of the API [explain]
  • 1.3.6. Include sample code for the main, most fundamental use case [explain]
  • 1.3.7. Include a link to the Developer Guide [explain]
  • 1.3.8. Include a link to the Cookbook [explain]
  • 1.3.9. Indicate related APIs
  • 1.3.10. Include the API version number [explain]
  • 1.3.11. Indicate deprecated API versions with the @deprecated tag
  • 1.3.12. Consider including a copyright notice [explain]
  • 1.3.13. Avoid lengthy package overviews
  • 1.3.14. Do not include implementation packages into published Javadoc

2. Type Design Checklist

2.1. General

  • 2.1.1. Ensure each type has a single, well-defined purpose
  • 2.1.2. Ensure types represent domain concepts, not design abstractions
  • 2.1.3. Limit the number of types [explain]
  • 2.1.4. Limit the size of types
  • 2.1.5. Follow consistent design patterns when designing related types
  • 2.1.6. Favor multiple (private) implementations over multiple public types
  • 2.1.7. Favor interfaces over class inheritance for expressing simple commonality in behavior [explain]
  • 2.1.8. Favor abstract classes over interfaces for decoupling API from implementation [explain]
  • 2.1.9. Favor enumeration types over constants
  • 2.1.10. Consider generic types [explain]
  • 2.1.11. Consider placing constraints on the generic type parameter
  • 2.1.12. Consider using interfaces to achieve similar effect to multiple inheritance
  • 2.1.13. Avoid designing for client extension
  • 2.1.14. Avoid deep inheritance hierarchies
  • 2.1.15. Do not use public nested types
  • 2.1.16. Do not declare public or protected fields
  • 2.1.17. Do not expose implementation inheritance to the client

2.2. Naming

  • 2.2.1. Use a noun or a noun phrase
  • 2.2.2. Use PascalCasing
  • 2.2.3. Capitalize only the first letter of acronyms [explain]
  • 2.2.4. Use accurate names for purpose of the type [explain]
  • 2.2.5. Reserve the shortest, most memorable name for the most frequently used type
  • 2.2.6. End the name of all exceptions with the word “Exception” [explain]
  • 2.2.7. Use singular nouns (Color, not Colors) for naming enumerated types [explain]
  • 2.2.8. Consider longer names [explain]
  • 2.2.9. Consider ending the name of derived class with the name of the base class
  • 2.2.10. Consider starting the name of an abstract class with the word “Abstract” [explain]
  • 2.2.11. Avoid abbreviations
  • 2.2.12. Avoid generic nouns
  • 2.2.13. Avoid synonyms
  • 2.2.14. Avoid type names used in related APIs
  • 2.2.15. Do not use names which differ in case alone
  • 2.2.16. Do not use prefixes
  • 2.2.17. Do not prefix interface names with “I”
  • 2.2.18. Do not use types names used in Java core packages [explain]

2.3. Classes

  • 2.3.1. Minimize implementation dependencies
  • 2.3.2. List public methods first [explain]
  • 2.3.3. Declare implementation methods private
  • 2.3.4. Define at least one public concrete class which extends a public abstract class [explain]
  • 2.3.5. Provide adequate defaults for the basic usage scenarios
  • 2.3.6. Design classes with strong invariants
  • 2.3.7. Group stateless, accessor and mutator methods together
  • 2.3.8. Keep the number of mutator methods at a minimum
  • 2.3.9. Consider providing a default no-parameter constructor [explain]
  • 2.3.10. Consider overriding equals(), hashCode() and toString() [explain]
  • 2.3.11. Consider implementing Comparable [explain]
  • 2.3.12. Consider implementing Serializable [explain]
  • 2.3.13. Consider making classes re-entrant
  • 2.3.14. Consider declaring the class as final [explain]
  • 2.3.15. Consider preventing class instantiation by not providing a public constructor [explain]
  • 2.3.16. Consider using custom types to enforce strong preconditions as class invariants
  • 2.3.17. Consider designing immutable classes [explain]
  • 2.3.18. Avoid static classes
  • 2.3.19. Avoid using Cloneable
  • 2.3.20. Do not add instance members to static classes
  • 2.3.21. Do not define public constructors for public abstract classes clients should not extend [explain]
  • 2.3.22. Do not require extensive initialization

2.4. Interfaces

  • 2.4.1. Provide at least one implementing class for every public interface
  • 2.4.2. Provide at least one consuming method for every public interface
  • 2.4.3. Do not add methods to a released public Java interface
  • 2.4.4. Do not use marker interfaces
  • 2.4.5. Do not use public interfaces as a container for constant fields

2.5. Enumerations

  • 2.5.1. Consider specifying a zero-value (“None” or “Unspecified”, etc) for enumeration types
  • 2.5.2. Avoid enumeration types with only one value
  • 2.5.3. Do not use enumeration types for open-ended sets of values
  • 2.5.4. Do not reserve enumeration values for future use
  • 2.5.5. Do not add new values to a released enumeration

2.6. Exceptions

  • 2.6.1. Ensure that custom exceptions are serialized correctly
  • 2.6.2. Consider defining a different exception class for each error type
  • 2.6.3. Consider providing extra information for programmatic access
  • 2.6.4. Avoid deep exception hierarchies
  • 2.6.5. Do not derive custom exceptions from other than Exception and RuntimeException
  • 2.6.6. Do not derive custom exceptions directly from Throwable
  • 2.6.7. Do not include sensitive information in error messages

2.7. Documentation

  • 2.7.1. Provide type overview for each type
  • 2.7.2. Follow standard Javadoc conventions
  • 2.7.3. Begin with a short, one sentence summary of the type
  • 2.7.4. Provide enough details to help deciding if and how to use the type
  • 2.7.5. Explain how to instantiate the type
  • 2.7.6. Provide code sample to illustrate the main use case for the type
  • 2.7.7. Include links to relevant sections in the Developer Guide
  • 2.7.8. Include links to relevant sections in the Cookbook
  • 2.7.9. Indicate related types
  • 2.7.10. Indicate deprecated types using the @deprecated tag
  • 2.7.11. Document class invariants
  • 2.7.12. Avoid lengthy type overviews
  • 2.7.13. Do not generate Javadoc for private fields and methods

3. Method Design Checklist

3.1. General

  • 3.1.1. Make sure each method does only one thing
  • 3.1.2. Ensure related methods are at the same level of granularity
  • 3.1.3. Ensure no boilerplate code is needed to combine method calls
  • 3.1.4. Make all method calls atomic
  • 3.1.5. Design protected methods with the same care as public methods
  • 3.1.6. Limit the number of mutator methods
  • 3.1.7. Design mutators with strong invariants
  • 3.1.8. Favor generic methods over a set of overloaded methods
  • 3.1.9. Consider generic methods
  • 3.1.10. Consider method pairs, where the effect of one is reversed by the other
  • 3.1.11. Avoid “helper” methods
  • 3.1.12. Avoid long-running methods
  • 3.1.13. Avoid forcing callers to write loops for basic scenarios
  • 3.1.14. Avoid “option” parameters to modify behavior
  • 3.1.15. Avoid non-reentrant methods
  • 3.1.16. Do not remove a released method
  • 3.1.17. Do not deprecate a released method without providing a replacement
  • 3.1.18. Do not change the signature of a released method
  • 3.1.19. Do not change the observable behavior of a released method
  • 3.1.20. Do not strengthen the precondition of an already released API method
  • 3.1.21. Do not weaken the postcondition of an already released API method
  • 3.1.22. Do not add new methods to released interfaces
  • 3.1.23. Do not add a new overload to a released API

3.2. Naming

  • 3.2.1. Begin names with powerful, expressive verbs
  • 3.2.2. Use camelCasing
  • 3.2.3. Reserve “get”, “set” and “is” for JavaBeans methods accessing local fields
  • 3.2.4. Use words familiar to callers
  • 3.2.5. Stay close to spoken English
  • 3.2.6. Avoid abbreviations
  • 3.2.7. Avoid generic verbs
  • 3.2.8. Avoid synonyms
  • 3.2.9. Do not use underscores
  • 3.2.10. Do not rely on parameter names or types to clarify the meaning of the method

3.3. Parameters

  • 3.3.1. Choose the most precise type for parameters
  • 3.3.2. Keep the meaning of the null parameter value consistent across related method calls
  • 3.3.3. Use consistent parameter names, types and ordering in related methods
  • 3.3.4. Place output parameters after the input parameters in the parameter list
  • 3.3.5. Provide overloaded methods with shorter parameter lists for frequently used default parameter values
  • 3.3.6. Use overloaded methods for operations with the same semantics on unrelated types
  • 3.3.7. Favor interfaces over concrete classes as parameters
  • 3.3.8. Favor collections over arrays as parameters and return values
  • 3.3.9. Favor generic collections over raw (untyped) collections
  • 3.3.10. Favor enumeration types over Boolean or integer types
  • 3.3.11. Favor putting single object parameters ahead of collection or array parameters
  • 3.3.12. Favor putting custom type parameters ahead of standard Java type parameters
  • 3.3.13. Favor putting object parameters ahead of value parameters
  • 3.3.14. Favor interfaces over concrete classes as return types
  • 3.3.15. Favor empty collections to null return values
  • 3.3.16. Favor returning values which are valid input for related methods
  • 3.3.17. Consider making defensive copies of mutable parameters
  • 3.3.18. Consider storing weak object references internally
  • 3.3.19. Avoid variable length parameter lists
  • 3.3.20. Avoid long parameter lists (more than 3)
  • 3.3.21. Avoid putting parameters of the same type next to each other
  • 3.3.22. Avoid out or in-out method parameters
  • 3.3.23. Avoid method overloading
  • 3.3.24. Avoid parameter types exposing implementation details
  • 3.3.25. Avoid Boolean parameters
  • 3.3.26. Avoid returning null
  • 3.3.27. Avoid return types defined in unrelated APIs, except core Java APIs
  • 3.3.28. Avoid returning references to mutable internal objects
  • 3.3.29. Do not use integer parameters for passing predefined constant values
  • 3.3.30. Do not reserve parameters for future use
  • 3.3.31. Do not change the parameter naming or ordering in overloaded methods

3.4. Error handling

  • 3.4.1. Throw exception only for exceptional circumstances
  • 3.4.2. Throw checked exceptions only for recoverable errors
  • 3.4.3. Throw runtime exceptions to signal API usage mistakes
  • 3.4.4. Throw exceptions at the appropriate level of abstraction
  • 3.4.5. Perform runtime precondition checks
  • 3.4.6. Throw NullPointerException to indicate a prohibited null parameter value
  • 3.4.7. Throw IllegalArgumentException to indicate an incorrect parameter value other than null
  • 3.4.8. Throw IllegalStateException to indicate a method call made in the wrong context
  • 3.4.9. Indicate in the error message which parameter violated which precondition
  • 3.4.10. Ensure failed method calls have no side effects
  • 3.4.11. Provide runtime checks for prohibited API calls made inside callback methods
  • 3.4.12. Favor standard Java exceptions over custom exceptions
  • 3.4.13. Favor query methods over exceptions for predictable error conditions

3.5. Overriding

  • 3.5.1. Use the @Override annotation
  • 3.5.2. Preserve or weaken preconditions
  • 3.5.3. Preserve or strengthen postconditions
  • 3.5.4. Preserve or strengthen the invariant
  • 3.5.5. Do not throw new types of runtime exceptions
  • 3.5.6. Do not change the type (stateless, accessor or mutator) of the method

3.6. Constructors

  • 3.6.1. Minimize the work done in constructors
  • 3.6.2. Set the value of all properties to reasonable defaults
  • 3.6.3. Use constructor parameters only as a shortcut for setting properties
  • 3.6.4. Validate constructor parameters
  • 3.6.5. Name constructor parameters the same as corresponding properties
  • 3.6.6. Follow the guidelines for method overloading when providing multiple constructors
  • 3.6.7. Favor constructors over static factory methods
  • 3.6.8. Consider a no parameter default constructor
  • 3.6.9. Consider a static factory method if you don’t always need a new instance
  • 3.6.10. Consider a static factory method if you need to decide the precise type of object at runtime
  • 3.6.11. Consider a static factory method if you need to access external resources
  • 3.6.12. Consider a builder when faced with many constructor parameters
  • 3.6.13. Consider private constructors to prevent direct class instantiation
  • 3.6.14. Avoid creating unnecessary objects
  • 3.6.15. Avoid finalizers
  • 3.6.16. Do not throw exceptions from default (no-parameter) constructors
  • 3.6.17. Do not add a constructor with parameters to a class released without explicit constructors

3.7. Setters and getters

  • 3.7.1. Start the name of methods returning non-Boolean properties with “get”
  • 3.7.2. Start the name of methods returning Boolean properties with “is”, “can” or similar
  • 3.7.3. Start the name of methods updating local properties with “set”
  • 3.7.4. Validate the parameter of setter methods
  • 3.7.5. Minimize work done in getters and setters
  • 3.7.6. Consider returning immutable collections from a getter
  • 3.7.7. Consider implementing a collection interface instead of a public propertie of a collection type
  • 3.7.8. Consider read-only properties
  • 3.7.9. Consider making a defensive copy when setting properties of mutable types
  • 3.7.10. Consider making a defensive copy when returning properties of mutable type
  • 3.7.11. Avoid returning arrays from getters
  • 3.7.12. Avoid validations which cannot be done with local knowledge
  • 3.7.13. Do not throw exceptions from a getter
  • 3.7.14. Do not design set-only properties (with public setter no public getter)
  • 3.7.15. Do not rely on the order properties are set

3.8. Callbacks

  • 3.8.1. Design with the strongest possible precondition
  • 3.8.2. Design with the weakest possible postcondition
  • 3.8.3. Consider passing a reference to the object initiating the callback as the first parameter of the callback method
  • 3.8.4. Avoid callbacks with return values

3.9. Documentation

  • 3.9.1. Provide Javadoc comments for each method
  • 3.9.2. Follow standard Javadoc conventions
  • 3.9.3. Begin with a short, one sentence summary of the method
  • 3.9.4. Indicate related methods
  • 3.9.5. Indicate deprecated methods using the @deprecated tag
  • 3.9.6. Indicate a replacement for any deprecated methods
  • 3.9.7. Avoid lengthy comments
  • 3.9.8. Document common behavioral patterns
  • 3.9.9. Document the precise meaning of a null parameter value (if permitted)
  • 3.9.10. Document the type of the method (stateless, accessor or mutator)
  • 3.9.11. Document method preconditions
  • 3.9.12. Document the performance characteristics of the algorithm implemented
  • 3.9.13. Document remote method calls
  • 3.9.14. Document methods accessing out-of-process resources
  • 3.9.15. Document which API calls are permitted inside callback methods
  • 3.9.16. Consider unit tests for illustrating the behavior of the method

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