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
This code is highly readable. It is a well-structured interface with clear Javadoc documentation explaining the contract for each method. The nesting is minimal and appropriate, the intent of the PeekingIterator is immediately obvious, and the code is concise. Each method declaration is on its own line with clear annotations. The reading flow is natural, starting with imports, then documentation, then method declarations in a logical order. The only minor issue is the slight complexity of the annotations, which might be unfamiliar to some readers, but this is standard for Guava and does not detract from readability.
Run 3
The code is highly readable with clear structure and intent. It follows standard Java interface conventions with well-organized imports, meaningful annotations, and comprehensive Javadoc. The interface is concise with only three methods, each having a single clear purpose. Nesting is minimal and the code flows naturally. Javadoc is thorough and helpful, particularly for the nuanced behavior of peek() and remove(). Minor deductions: the multiline @throws alignment in the peek() Javadoc is slightly awkward, and there is no blank line after the @CanIgnoreReturnValue import before the java.util imports. Overall this is exemplary production-quality code that clearly communicates its contract to implementers.
Run 1
Code Structure: A well-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 documentation explain lookahead behavior, return guarantees, and removal restrictions. Code length: Concise declarations; the longer comments provide useful API-contract details rather than unnecessary verbosity. Action granularity: Each declaration and annotation occupies its own line, making individual elements easy to identify. Reading flow: Methods progress naturally from peek() to next() to remove(), with relevant documentation immediately preceding each. Minor distractions include tightly packed package/import formatting and awkward wrapping in the documentation link.
Run 2
Code Structure: The interface is logically organized, with imports, interface documentation, and clearly separated method declarations. Nesting: There is no nested control flow; the structure is flat and easy to scan. Clarity of intent: Descriptive naming and precise Javadoc explain lookahead behavior, exception conditions, and interactions between peek(), next(), and remove(). Code length: The declarations are concise; documentation is extensive 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() is natural. Minor readability costs include dense annotations and awkward wrapping of some Javadoc links.
Run 3
Code Structure: The interface is logically organized, with imports, interface documentation, and related method declarations clearly separated. Nesting: There is only the interface scope, 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; the longer documentation provides useful API-contract details rather than unnecessary verbosity. Action granularity: Each annotation and method declaration occupies its own line, with no combined actions. Reading flow: The progression from peek() to next() to remove() is natural. Minor distractions include the awkwardly wrapped documentation link, annotation density, and the lack of a blank line between the package declaration and imports.