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 exceptionally readable. It is a concise interface definition with clear, logical structure: imports, Javadoc overview, interface declaration, and three well-documented methods. Nesting is flat. Javadoc comments clearly explain intent, edge cases, and contracts for each method. Code length is minimal and appropriate. Each method declaration is a single, clear action. Reading flow is natural, moving from overview to specific methods. Minor deductions could be for verbosity of Javadoc for library distribution, but this is idiomatic for public APIs.
Run 3
The code is highly readable due to its clear structure, minimal nesting, and focused method definitions. It is a well-documented interface with concise method signatures, each serving a single, obvious purpose. Documentation is thorough and contextual, explaining side effects ('peek' affects removal) and usage constraints, which greatly clarifies intent. The reading flow is natural, starting with class-level documentation and moving through methods logically. Action granularity is clean, with no clutter. Length is appropriate for an interface with three methods, avoiding unnecessary verbosity while maintaining completeness. Only minor deductions are for the import list's slight redundancy and the complexity of some Javadoc links, but overall this code exemplifies high readability for a collection utility interface.
Run 1
Code Structure: Cleanly organized interface with imports, class-level documentation, and logically ordered method declarations. Nesting: Flat, with no nested control flow. Clarity of intent: Descriptive naming and precise Javadoc clearly explain lookahead behavior, return guarantees, and removal restrictions. Code length: Concise declarations; documentation is substantial but relevant to the API contract. Action granularity: Each method declaration and annotation occupies its own line, making responsibilities easy to distinguish. Reading flow: Naturally progresses from the interface purpose to peek(), next(), and remove(). Minor distractions include tightly packed package/import lines and awkward wrapping in the documentation link, but overall readability is excellent.
Run 2
Code Structure: A small, logically organized interface with imports, interface documentation, and clearly separated method declarations. Nesting: Flat, with no nested control flow. Clarity of intent: Descriptive names and precise Javadoc clearly explain lookahead behavior, method relationships, and removal restrictions. Code length: The declarations are concise; documentation is proportionate to the behavioral contract, though annotations and wrapped Javadoc add some visual overhead. Action granularity: Each method declaration and annotation occupies its own line; no actions are combined. Reading flow: The sequence from peek() to next() to remove() naturally presents the interface's behavior. Minor formatting issues, such as the missing blank line after the package declaration and awkwardly wrapped documentation links, slightly reduce readability.
Run 3
Code Structure: A 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, return guarantees, and removal restrictions. 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: Methods follow a natural peek, next, remove sequence. Minor readability costs come from annotation density, awkwardly wrapped Javadoc links, and the lack of a blank line after the package declaration.