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 has a clean interface structure, minimal nesting, and clear intent through descriptive Javadoc. Methods are concise, each performs one logical action, and the reading flow is natural. Minor deducts for verbose annotations and Javadoc length slightly reducing scannability.
Run 3
The code is highly readable. The structure is logical, with a clean package declaration, clear imports, and a well-organized interface definition. Nesting is minimal, and clarity of intent is excellent, especially with Javadoc comments that explain the contract of peek(), next(), and remove(). The code length is appropriate for an interface, and action granularity is well-controlled, with each method declaration on its own line. Reading flow is natural, following standard Java conventions. Minor deductions could be made for the slight verbosity of Javadoc, but overall the code is concise and maintainable.
Run 1
Code Structure: A small, logically organized interface with imports, class documentation, and related method declarations. Nesting: Flat declarations with no nested control flow. Clarity of intent: Descriptive naming and detailed Javadoc clearly explain lookahead behavior, method relationships, and removal constraints. Code length: The interface is concise; documentation is longer than the declarations but provides useful contract details. Action granularity: Each method declaration and annotation occupies its own line, with no combined actions. Reading flow: The sequence from peek() to next() to remove() naturally follows iterator usage. Minor readability drawbacks include densely wrapped Javadoc links and the lack of visual separation between the package declaration and imports.
Run 2
Code Structure: A small, logically organized interface with imports, class documentation, and clearly separated method declarations. Nesting: Flat, with no nested control flow. Clarity of intent: Descriptive names and precise Javadoc explain lookahead behavior, guarantees, and removal restrictions. Code length: The declarations are concise; documentation is longer but justified by subtle API contracts. Action granularity: Each declaration and annotation occupies its own line, with no bundled operations. Reading flow: Methods progress naturally from peek() to next() to remove(). Minor distractions include densely wrapped Javadoc links, several annotations requiring library familiarity, and the lack of a blank line after the package declaration.
Run 3
Code Structure: A well-organized interface with imports, interface documentation, and logically ordered method declarations. Nesting: Minimal nesting, with no complex control flow. Clarity of intent: Descriptive names and precise Javadocs clearly explain lookahead behavior, method guarantees, and removal restrictions. Code length: The executable API is concise; documentation is longer but provides useful contract details rather than unnecessary repetition. Action granularity: Each method declaration and annotation occupies its own line, making individual elements easy to distinguish. Reading flow: The progression from peek() to next() to remove() is natural. Minor distractions include annotation density, wrapped Javadoc links, and the lack of a blank line between the package declaration and imports.