Methods

• Thread-safety: Always document the thread-safety level of a class or static method, as described in Item 82
• Serializability: If a class is serializable, document its serialized form, as described in Item 87

Example thread-safety documentation:

/**
 * This class is thread-safe. All public methods use internal synchronization
 * to ensure consistent state when accessed concurrently.
 */
public class ThreadSafeCounter {
    // Implementation...
}

Creating a truly immutable class with mutable components requires:

1. Make the class final to prevent subclassing

2. Make all fields private and final

3. Don't provide any methods that modify state

4. Defensively copy all mutable components in the constructor:

   // Constructor with defensive copying
   public ImmutablePeriod(Date start, Date end) {
       // Make defensive copies BEFORE validation
       this.start = new Date(start.getTime());
       this.end = new Date(end.getTime());
       
       // Validate using the copies
       if (this.start.compareTo(this.end) > 0)
           throw new IllegalArgumentException("Start after end");
   }

5. Defensively copy mutable components in accessors:

   // Accessor with defensive copying
   public Date getStart() {
       return new Date(start.getTime());
   }

6. Override equals(), hashCode(), and toString() appropriately

Best practice: Use immutable components where possible (e.g., Instant instead of Date) to avoid defensive copying entirely.

Documentation comments alone are not sufficient for complex APIs consisting of multiple interrelated classes. In these cases:

1. Supplement documentation comments with an external document describing the overall architecture of the API
2. Include links to this external document in the relevant class or package documentation comments
3. Ensure the external document explains relationships between classes, usage patterns, and the conceptual framework of the API

This provides necessary context that can't be captured in individual element documentation.

Objects.requireNonNull() (Java 7+):

• Advantages:
  • Returns the validated object (enables validation during assignment)
  • Allows custom exception messages
  • Cleaner than manual checks

  // Inline usage with assignment
  this.strategy = Objects.requireNonNull(strategy, "Strategy cannot be null");
  
  // Standalone usage
  Objects.requireNonNull(input, "Input required");

Range-checking facilities (Java 9+):

• Methods: checkFromIndexSize(), checkFromToIndex(), checkIndex()
• Advantages:
  • Simplifies common index validation logic
  • Standardized exception behavior

  // Validates index is within [0, array.length)
  int index = Objects.checkIndex(userIndex, array.length);
  
  // Validates range [fromIndex, toIndex) is within [0, array.length)
  Objects.checkFromToIndex(fromIndex, toIndex, array.length);

Limitations:

1. Range-checking doesn't allow custom error messages
2. Range methods only designed for array/list indices
3. Cannot handle closed ranges (ranges including both endpoints)
4. Only checks common patterns, not complex validations
5. No built-in support for other common validations (positivity, emptiness)

Best practice: Use these utilities for standard validations, but implement custom validation logic when needed for complex requirements.

• Technique 1: Break into multiple methods

  • Each method requires only a subset of parameters
  • Advantage: Clearer method purpose, better discoverability
  • Risk: Can lead to too many methods if not done carefully
  • Helps increase orthogonality of the API

• Technique 2: Create helper classes

  • Group related parameters into static member classes
  • Ideal for frequently occurring parameter groups
  • Example: Replace rank and suit parameters with a Card class
  • Advantage: Reduces parameter count and increases semantic clarity

• Technique 3: Builder pattern for method invocation

  • Create object representing all parameters
  • Allow "setter" methods for each parameter
  • Execute computation with final "execute" method
  • Especially useful for methods with many optional parameters
  • Advantage: Clear which parameter is which, supports optional parameters

• Example of increased orthogonality (Technique 1):

// Instead of this (3 parameters):
int firstIndex = list.findFirstInSubList(element, fromIndex, toIndex);

// Use existing methods together:
List<E> subList = list.subList(fromIndex, toIndex);
int firstIndex = subList.indexOf(element);

• Method Naming Guidelines:

  • Always follow standard naming conventions
  • Choose understandable names consistent with other names in the same package
  • Aim for consistency with broader consensus (e.g., Java library APIs)
  • Avoid long method names
  • Look to Java library APIs for guidance

• Method Count Principle: "Every method should pull its weight"

  • Too many methods make a class difficult to:
    • Learn
    • Use
    • Document
    • Test
    • Maintain
  • For interfaces, too many methods burden implementors

• Guidelines for Adding Methods:

  • For each action, provide one fully functional method
  • Only add "shorthand" convenience methods if they'll be frequently used
  • When in doubt, leave it out
  • Consider using different names for methods rather than overloading
    • Example: writeBoolean(), writeInt(), writeLong() instead of overloaded write()

• ObjectOutputStream Example: Has different method names for each type instead of overloading:

void writeBoolean(boolean v);
void writeInt(int v);
void writeLong(long v);
// Instead of overloaded write(boolean), write(int), write(long)

When adding a more general method alongside an existing specific method:

1. Have the more specific method forward to the more general one using an explicit cast:

// Existing specific method
public boolean contentEquals(StringBuffer sb) {
    // Forward to the more general implementation
    return contentEquals((CharSequence) sb);
}

// New general method
public boolean contentEquals(CharSequence cs) {
    // Implementation that works for all CharSequences
    // ...
}

This approach:

• Ensures identical behavior for both methods when given the same object
• Prevents confusion about which method gets called
• Centralizes logic in one place to avoid duplication
• Maintains backward compatibility while allowing evolution

Pitfall: Never return Optional<Integer>, Optional<Double> or Optional<Long> as this causes double boxing (primitive → boxed → Optional), creating significant performance overhead.

Alternatives:

• Use specialized primitive Optional classes:
  • OptionalInt for int values
  • OptionalLong for long values
  • OptionalDouble for double values

// Inefficient - causes double boxing
public Optional<Integer> findValue() { ... }

// Efficient - uses specialized container
public OptionalInt findValue() {
    // When value exists
    return OptionalInt.of(123);
    
    // When no value
    return OptionalInt.empty();
}

Note: The "minor" primitive types (Boolean, Byte, Character, Short, Float) don't have specialized Optional classes, so boxing those in a regular Optional is acceptable.

When you're certain a value exists, you can use:

// Direct access when you're certain the value exists
Element element = optionalElement.get();

Consequences if wrong:

• Throws NoSuchElementException if the Optional is empty
• Creates an unexpected runtime failure
• No compile-time safety

Better alternatives:

1. Use assertion or validation before calling get():

assert optionalElement.isPresent() : "Element must be present";
Element element = optionalElement.get();

2. Use orElseThrow with a specific exception:

Element element = optionalElement.orElseThrow(() -> 
    new IllegalStateException("Element must be present but was not"));

3. Design defensive code that doesn't assume presence:

optionalElement.ifPresent(element -> processElement(element));

Best practice: Only use get() when you have a provable guarantee the Optional contains a value.

Documenting Preconditions and Postconditions:

Preconditions: Conditions that must be true before a method is called

• Document in @param tags for affected parameters
• Document in @throws tags for unchecked exceptions
• May specify in the method description

Postconditions: Conditions guaranteed to be true after method execution

• Document in the method description
• Document in @return tag

Example:

/**
 * Returns a substring of this string, starting at the specified index
 * and extending to the end of the string.
 *
 * @param beginIndex the beginning index, inclusive; must be non-negative
 *        and less than or equal to the length of this string
 * @return the specified substring
 * @throws IndexOutOfBoundsException if {@code beginIndex} is negative or
 *         greater than the length of this string
 */
public String substring(int beginIndex) { ... }

Relationship between @throws and preconditions:

• Unchecked exceptions (@throws) document precondition violations
• Each @throws tag for an unchecked exception should:
  1. State precisely what conditions trigger the exception
  2. Use the form "if..." followed by the violation condition
  3. Include code sample in {@code} tags when condition is complex

Best practices:

• Be explicit about nullability requirements
• Document side effects (observable state changes)
• Use specific language for mutability guarantees
• Specify thread safety expectations