Source code
package com.google.common.collect;
import com.google.common.annotations.GwtCompatible;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import com.google.errorprone.annotations.DoNotMock;
import java.util.Iterator;
import java.util.NoSuchElementException;
import org.jspecify.annotations.Nullable;
/**
* An iterator that supports a one-element lookahead while iterating.
*
* <p>See the Guava User Guide article on <a href=
* "https://github.com/google/guava/wiki/CollectionHelpersExplained#peekingiterator">{@code
* PeekingIterator}</a>.
*
* @author Mick Killianey
* @since 2.0
*/
@DoNotMock("Use Iterators.peekingIterator")
@GwtCompatible
public interface PeekingIterator<E extends @Nullable Object> extends Iterator<E> {
/**
* Returns the next element in the iteration, without advancing the iteration.
*
* <p>Calls to {@code peek()} should not change the state of the iteration, except that it
* <i>may</i> prevent removal of the most recent element via {@link #remove()}.
*
* @throws NoSuchElementException if the iteration has no more elements according to {@link
* #hasNext()}
*/
@ParametricNullness
E peek();
/**
* {@inheritDoc}
*
* <p>The objects returned by consecutive calls to {@link #peek()} then {@link #next()} are
* guaranteed to be equal to each other.
*/
@CanIgnoreReturnValue
@Override
@ParametricNullness
E next();
/**
* {@inheritDoc}
*
* <p>Implementations may or may not support removal when a call to {@link #peek()} has occurred
* since the most recent call to {@link #next()}.
*
* @throws IllegalStateException if there has been a call to {@link #peek()} since the most recent
* call to {@link #next()} and this implementation does not support this sequence of calls
* (optional)
*/
@Override
void remove();
}
Run 1
The code is highly readable. It has clear structure as an interface with well-organized Javadoc comments, a single logical purpose, and no complex nesting. Intent is unambiguous through descriptive method names and documentation. The code is concise, with each method declaration on its own line and no unnecessary verbosity. Action granularity is appropriate for an interface definition. Reading flow is natural: the peek() method is defined first as the primary addition, followed by overridden next() and remove() with clarifying documentation. Minor deductions come from the long Javadoc blocks which somewhat interrupt the code flow, and the generic type parameter '<E extends @Nullable Object>' adds slight complexity. Overall, the interface is clean, well-documented, and easy to understand.
Run 2
The code is highly readable. It is a well-structured interface with clear Javadoc documentation explaining purpose, behavior, and edge cases. The methods are minimal and concise, each with a single clear responsibility. There is no deep nesting or unnecessary complexity. Annotations are used appropriately to signal intent (e.g., @DoNotMock, @GwtCompatible, @ParametricNullness). The reading flow is natural: package, imports, class-level docs, then method declarations with detailed contracts. Naming is conventional and unambiguous. The only minor drawbacks are the slightly dense generic type declaration and the presence of multiple annotations per method, but these are idiomatic for Guava and do not meaningfully impact readability. Overall, the code is easy to understand and maintain.
Run 3
The code is highly readable. It has a clear, logical structure with class-level Javadoc, interface declaration, and well-documented methods. Nesting is effectively flat, with only one level of indentation inside the interface. Intent is unambiguous: it defines a PeekingIterator contract with clear semantics for peek, next, and remove. The code length is concise, containing only essential elements and documentation. Action granularity is appropriate, with each method signature and annotation on its own line. Reading flow is natural, from package declaration to imports, then from overview documentation to specific method contracts. Minor deductions for the line wrapping in some Javadoc tags and annotations, which slightly reduces visual scanning efficiency, but overall this is an exemplary example of clear Java API design.
Run 1
Code Structure: Clearly organized interface with imports, interface documentation, and individually documented methods. Nesting: Flat declarations with no nested control flow. Clarity of intent: Descriptive naming and precise documentation explain lookahead behavior, return guarantees, and removal constraints. Code length: The interface is concise; extensive comments are justified by subtle behavioral contracts. Action granularity: Each method declaration and annotation occupies its own line, with no combined operations. Reading flow: Methods follow a natural progression from peek() to next() to remove(). Minor readability distractions include tightly packed package/import declarations and awkward wrapping in the documentation link.
Run 2
Code Structure: The interface is logically organized, with imports, interface documentation, and three clearly separated method declarations. Nesting: There is no control-flow nesting; declarations remain flat within the interface. Clarity of intent: Descriptive names and precise Javadoc clearly explain lookahead behavior, guarantees, and removal restrictions. Code length: The implementation surface is concise; extensive documentation is justified by subtle iterator contracts. Action granularity: Each method declaration and annotation occupies its own line, with no combined operations. Reading flow: The progression from peek() to next() to remove() naturally follows iterator usage. Minor distractions include annotation density, wrapped Javadoc links, and the lack of a blank line between the package declaration and imports.
Run 3
Code Structure: A logically organized interface with related methods and documentation grouped together. Nesting: Flat declarations with no nested control flow. Clarity of intent: Descriptive names and precise Javadocs clearly explain lookahead behavior, return guarantees, and removal restrictions. Code length: The interface is concise; documentation is substantial but justified by subtle behavioral contracts. Action granularity: Each method declaration and annotation occupies its own line, with no combined actions. Reading flow: The progression from peek() to next() to remove() naturally follows iterator usage. Minor readability drawbacks include annotation density, awkwardly wrapped Javadoc links, and the lack of a blank line between the package declaration and imports.