Chapter: Method Design

• Focus: Usability, robustness and flexibility in method design.
• Coverage: Parameter and return value handling, method signature design, and documentation.

Item 49: Check Parameter Validity

- Restrictions on Parameters:
Methods and constructors generally have restrictions on parameter values ​​(e.g., non-negative indices, non-null references).
These restrictions must be documented and verified at the beginning of the method.

- Importance of Verification:
Detect errors as early as possible to avoid unexpected failures or incorrect behavior in the method.
Methods that don't check their parameters can cause hard-to-debug crashes.

- Exceptions Documentation:
Use the @throws Javadoc tag to document exceptions thrown in case of constraint violations.
Common exceptions: IllegalArgumentException, IndexOutOfBoundsException, NullPointerException.

Parameter Check Example:

public static int mod(int x, int y) {
    if (y 



- Usage of Objects.requireNonNull:

Introduced in Java 7, it is used to check nullability of objects.

Returns the value passed after verification: 


this.m = Objects.requireNonNull(m, "Parâmetro 'm' não pode ser nulo");





- Ranges Check (Java 9):

checkFromIndexSize, checkFromToIndex, and checkIndex methods for checking indexes in lists and arrays.

Less flexible, mainly used for collections.

**

• Parameter Checking in Non-Public Methods:** For non-exported methods, use assertions to check parameters:

assert x > 0 : "Valor de x deve ser positivo";

- Special Cases:
Builders should always check the validity of stored parameters for later use.
Exceptions can be made for costly checks, where the check is implicit during the calculation.

- Implicit Verification Example:
Collections.sort(List) assumes that objects are mutually comparable. Verification occurs during the sorting process.

- Translation of Exceptions:
When implicit checking throws the wrong exception, use "exception translation" to throw the correct exception.

- Flexibility in Restrictions:
Methods should be designed to be as general as possible, imposing as few restrictions as necessary.

- Conclusion:
Document and implement parameter validity checks on methods and constructors. Practice is essential to avoid future errors and facilitate debugging.