Nullaway

Core Principles

1. Migration to @NullMarked vs New Code

The approach differs significantly depending on whether you are migrating existing code to @NullMarked or writing new code in an already @NullMarked context:

• Migration to @NullMarked:
  • Goal: Satisfy the static analyzer while minimizing functional changes to avoid regressions.
  • Practice: Use NullUtil.assumeNonNull() when dereferencing immediately to satisfy the analyzer without runtime overhead. Use assert when storing or returning values. Use if guards occasionally if it helps avoid assertions, but avoid changing the logic.
• New Code (and modifying already @NullMarked code):
  • Goal: Build robust, null-safe components from the ground up.
  • Practice: Be more liberal with asserts to enforce contracts. Rely on correct annotations (or their absence for implicit @NonNull) and only use null guards for @Nullable values. assumeNonNull() should generally not be used for new code.

2. No Functional Changes (For Migration)

• Rule: When migrating existing code, avoid adding new throwing runtime checks where they did not exist before, unless guided by the rules below.

3. assumeNonNull vs assert != null

The choice between assumeNonNull and Java assert depends on how the value is used:

• Dereferencing @Nullable values immediately: Use NullUtil.assumeNonNull(x).
  • Example:

    var value = mSupplier.get();
    assumeNonNull(value);
    value.doSomething();

  • Why: If it is null, it will NPE on the dereference anyway. assumeNonNull is a no-op that satisfies the analyzer without adding redundant runtime checks.
  • Style Rule: assumeNonNull() should be on a separate line, almost always, rather than used inline.
  • Note: This rule is primarily for migrations to avoid functional changes. For new code, rely on correct annotations and avoid assumeNonNull().
• Passing @Nullable values to non-null parameters: First, look into the call tree of the receiver class and see if that parameter should be annotated as @Nullable or not. If it can natively handle null, update the method signature instead of adding an assertion. If it strictly requires a non-null value, THEN you MUST use a Java assert x != null; on a preceding line before passing or storing it.

  [!CAUTION] NEVER use assumeNonNull(x) to pass a @Nullable value to a non-null parameter or to return it from a non-nullable method. This is STRICTLY FORBIDDEN. You MUST use a Java assert on a preceding line to add a runtime check.

  • Bad Example:

    mReceiver.setSomething(assumeNonNull(nullableValue));

  • Good Example:

    assert nullableValue != null;
    mReceiver.setSomething(nullableValue);

• Returning @Nullable values from non-nullable methods: First, consider if the method's return type can be safely updated to @Nullable. If it cannot (e.g., because it implements an interface or strictly enforces a non-null contract), you MUST use a Java assert x != null; on a preceding line before returning the value. Using assumeNonNull(x) inline within a return statement is strictly forbidden.
  • Bad Example:

    return assumeNonNull(nullableValue);

  • Good Example:

    assert nullableValue != null;
    return nullableValue;

• Why: Asserts add a runtime check (active in tests/debug) which is an acceptable functional change. We rely on instrumentation tests to validate these changes.
  • Deep Investigation Rule: Before asserting or assuming non-null for a passed value, investigate the call tree. If the method being called can be updated to consider the parameter @Nullable, prefer updating the method signature over adding an assertion.
  • Warning: Be careful with assert value != null on Supplier.get() during initialization. If the supplier value is set LATER (as is common with UI wiring), the assert might fail immediately during construction. In such cases, the getter should return @Nullable and callers should handle it, rather than asserting non-null immediately.

4. Handling Suppliers and Generics

• Problem: Passing a Supplier<@Nullable T> to a constructor that expects Supplier<T> (non-nullable), or vice versa.
• Preference: Prefer using exact types like Supplier<@Nullable T> rather than wildcards like Supplier<? extends @Nullable T> in method signatures and fields.
• Upcasting: SupplierUtils.upcast() is strictly for upcasting the type parameter to a base class (e.g., Supplier<DerivedT> to Supplier<BaseT>). Do NOT use it solely for handling nullability differences (e.g., Supplier<T> to Supplier<@Nullable T>).
• Handling Nullability Generic Invariance: You generally shouldn't need to use lambdas or upcast to bridge nullability differences (e.g., passing Supplier<T> to Supplier<@Nullable T>) if you are passing around subclasses of ObservableSupplier.
• Design Principle: If a supplier can return null, the receiver class must be updated to accept Supplier<@Nullable T> and handle the nullity. Never use hacks or assertions to force a Supplier<@Nullable T> to act as a non-nullable Supplier<T>.
• Good Fix: Alter the receiver class to accept Supplier<@Nullable T>.
  • Then, handle the nullability inside the receiver class using the rules above (assumeNonNull or assert).
• Supplier Wrappers (Anti-Pattern): Do NOT introduce a new lambda just to wrap a supplier call with an assertion. For example, do not do this: () -> assumeNonNull(supplier.get()) or this: () -> { var x = getter(); assert x != null; return x; }. These are anti-patterns.
  • If using ObservableSupplier: Pass supplier.asNonNull() directly. This returns a NonNullObservableSupplier which satisfies Supplier<@NonNull T>.
  • Otherwise: Change the receiver's parameter type to Supplier<@Nullable T> and handle the nullity inside the receiver class. Do not force non-nullability at the call site with hacks.
• Supplier Argument Types: Consider changing Supplier arguments to Supplier<@Nullable T> or MonotonicObservableSupplier<T> in method signatures to avoid forcing non-nullability on callers.