Source code
package com.google.common.collect;
import static com.google.common.base.Preconditions.checkNotNull;
import com.google.common.annotations.GwtCompatible;
import com.google.common.annotations.GwtIncompatible;
import com.google.common.annotations.J2ktIncompatible;
import com.google.errorprone.annotations.concurrent.LazyInit;
import java.io.Serializable;
import org.jspecify.annotations.Nullable;
/** An ordering that uses the natural order of the values. */
@GwtCompatible
final class NaturalOrdering extends Ordering<Comparable<?>> implements Serializable {
static final NaturalOrdering INSTANCE = new NaturalOrdering();
/*
* TODO: b/287198172 - Consider eagerly initializing these, maybe making them static. But that
* would lead to at least slighly more work at startup time.
*/
@LazyInit private transient @Nullable Ordering<@Nullable Comparable<?>> nullsFirst;
@LazyInit private transient @Nullable Ordering<@Nullable Comparable<?>> nullsLast;
@Override
@SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
public int compare(Comparable<?> left, Comparable<?> right) {
checkNotNull(left); // for GWT
checkNotNull(right);
return ((Comparable<Object>) left).compareTo(right);
}
@Override
@SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
public <S extends Comparable<?>> Ordering<@Nullable S> nullsFirst() {
Ordering<@Nullable Comparable<?>> result = nullsFirst;
if (result == null) {
result = nullsFirst = super.<Comparable<?>>nullsFirst();
}
return (Ordering<@Nullable S>) result;
}
@Override
@SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
public <S extends Comparable<?>> Ordering<@Nullable S> nullsLast() {
Ordering<@Nullable Comparable<?>> result = nullsLast;
if (result == null) {
result = nullsLast = super.<Comparable<?>>nullsLast();
}
return (Ordering<@Nullable S>) result;
}
@Override
@SuppressWarnings("unchecked") // TODO(kevinb): the right way to explain this??
public <S extends Comparable<?>> Ordering<S> reverse() {
return (Ordering<S>) ReverseNaturalOrdering.INSTANCE;
}
// preserving singleton-ness gives equals()/hashCode() for free
private Object readResolve() {
return INSTANCE;
}
@Override
public String toString() {
return "Ordering.natural()";
}
private NaturalOrdering() {}
@GwtIncompatible @J2ktIncompatible private static final long serialVersionUID = 0;
}
Run 1
The code is well-structured and readable overall. The class has a clear single responsibility and uses sensible method ordering. Method names like nullsFirst(), nullsLast(), and reverse() clearly convey intent. The lazy initialization pattern for nullsFirst and nullsLast follows a consistent, recognizable structure. Indentation is consistent, and nesting is minimal. The @SuppressWarnings annotations with TODO comments are somewhat noisy but explain why the suppressions exist. The compare() method includes null checks with comments for GWT compatibility, clarifying intent. One minor readability drawback is the repeated @SuppressWarnings("unchecked") pattern with identical TODO comments, which adds visual clutter. Variable names like left, right, and result are clear. The class is concise, with no unnecessary code. Action granularity is reasonable—one logical operation per line in most cases. The serialization field placement at the bottom with annotations is logical. Overall, the code is maintainable and easy to follow for a developer familiar with Guava patterns.
Run 2
The code is well-structured with clear logical organization and consistent formatting. Nesting is minimal, with only single-level if statements for lazy initialization. The intent of each method is clear, though the multiple @SuppressWarnings annotations with unresolved TODO comments reduce clarity. Code length is appropriate with no unnecessary verbosity. Each line performs a single action, maintaining good granularity. Reading flow is natural and follows a logical progression from fields to methods, ending with utility methods. The main readability issues are the repetitive nullsFirst/nullsLast pattern and the unclear type-casting suppressions that leave ambiguity about why unchecked warnings are acceptable.
Run 3
The code is well-structured and highly readable for an experienced Java developer. It follows a logical organization with clear class declaration, fields, and methods. The nesting is minimal—only simple null checks within methods. Intent is clear: a singleton natural ordering implementation. The code is concise and avoids unnecessary complexity. Each line generally performs one action, maintaining good action granularity. Reading flow is natural, with methods ordered logically (compare, nullsFirst, nullsLast, reverse, readResolve, toString). The use of comments explains non-obvious decisions like lazy initialization and GWT compatibility. Some minor readability costs come from the generic type declarations (e.g., 'Ordering<@Nullable Comparable<?>>') and the pervasive 'TODO(kevinb)' comments, but these are inherent to the codebase's complexity rather than poor style. Overall, it's a clean implementation that would be straightforward to maintain for developers familiar with the codebase.
Run 1
Code Structure: Logically organized around a singleton ordering, with small, focused methods; placing serialization metadata and the constructor last slightly weakens grouping. Nesting: Very shallow, with only single-level conditionals for lazy initialization. Clarity of intent: Descriptive names and the class comment make natural ordering and null handling clear, although complex generic annotations, unchecked casts, and unresolved TODOs require extra interpretation. Code length: Concise overall; parallel nullsFirst and nullsLast implementations are reasonable duplication. Action granularity: Most lines perform one action, but chained assignments combine local assignment and cache updates, while several annotations share declaration lines. Reading flow: Methods follow a natural progression from comparison to ordering variants and singleton support, though dense type signatures and repeated suppression comments interrupt scanning.
Run 2
Code Structure: Logically organized around a singleton natural ordering, with small, focused methods. Nesting: Minimal; caching methods contain only one conditional level. Clarity of intent: Descriptive names and the class documentation explain the purpose, although complex generic types, unchecked casts, and repeated unresolved TODOs add cognitive overhead. Code length: Concise overall; duplicated caching patterns are limited and understandable. Action granularity: Most statements perform one action, but chained assignments update both the cache and local variable on one line, and compressed annotation declarations reduce scanability. Reading flow: Methods follow a coherent progression from comparison to ordering variants and singleton support; dense type annotations and minor formatting inconsistencies occasionally interrupt the flow.
Run 3
Code Structure: Well-organized class with focused methods and clear singleton implementation. Nesting: Minimal, with only single-level conditionals for lazy initialization. Clarity of intent: Descriptive names and comments establish natural ordering, null handling, and singleton preservation; complex generic types, unchecked casts, and unresolved TODOs add friction. Code length: Concise overall, though repeated suppression comments and similar caching methods introduce minor repetition. Action granularity: Most statements perform one action, but chained assignments combine local assignment and cache updates. Reading flow: Methods follow a sensible progression from comparison to ordering variants and serialization support; dense annotations, tightly packed imports, and the trailing serialization constant slightly interrupt the flow.