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
This code is highly readable. The structure is logical and follows standard Java interface conventions, with clear separation between imports, Javadoc, and method declarations. Nesting is minimal—there are no deeply nested blocks, only annotations and Javadoc. Intent is unambiguous: the interface clearly extends Iterator and adds a peek() method, with thorough documentation explaining behavior and edge cases. Code length is appropriate; the Javadoc is extensive but justified for a public API. Action granularity is excellent—each method is a single declaration with clear purpose. Reading flow is natural, progressing from class-level documentation to method-level details. The only minor deductions are for the verbose Javadoc with HTML tags (necessary for Guava but slightly dense) and multiple annotations that add visual noise, but these are standard practice for this codebase.
Run 2
The code is highly readable. It is a single, focused interface with a clear purpose. Structure is logical, with imports, Javadocs, and method declarations arranged conventionally. Nesting is flat and minimal. The intent is explicit through descriptive method names and thorough Javadocs. Code length is concise, avoiding unnecessary methods or complexity. Each action is self-contained per line. The reading flow is natural, moving from broader context (package, imports) to the interface declaration and then to method contracts. Minor deductions for verbose Javadocs with HTML tags, which add some visual noise. Overall, excellent clarity and maintainability.
Run 3
The code is highly readable with a clear, logical structure. It defines a well-documented interface with a single responsibility, following standard Java conventions. Nesting is minimal, limited to the interface and method declarations. Intent is explicitly conveyed through descriptive names and comprehensive Javadoc comments that explain method behavior, edge cases, and exceptions. Code length is appropriate—concise yet thorough documentation adds value without unnecessary verbosity. Each line performs a single action, maintaining clear action granularity. The reading flow is natural, progressing from imports and class-level documentation to method declarations in order of importance. Overall, this represents exemplary interface design and documentation practices.
Run 1
Code Structure: A well-organized interface with imports, interface documentation, and clearly separated method declarations. Nesting: Flat, with no nested control flow. Clarity of intent: Descriptive naming 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 follow a natural peek-next-remove sequence, with documentation immediately preceding each declaration. Minor readability drawbacks include tightly packed imports and awkward wrapping in some Javadoc links.
Run 2
Code Structure: The interface is logically organized, with imports, type documentation, and three clearly separated method declarations. Nesting: The structure is flat, with no nested control flow. Clarity of intent: Descriptive naming and precise Javadoc explain lookahead behavior, method guarantees, and removal constraints. Code length: The declarations are concise; documentation is longer but justified by subtle contract details. 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 distractions include annotation density, wrapped Javadoc links, and the lack of a blank line after the package declaration.
Run 3
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 naming and precise Javadoc explain lookahead behavior, method relationships, and removal constraints. Code length: Concise declarations; documentation is proportionate to the subtle API contract, though annotations add some visual overhead. Action granularity: Each declaration and annotation occupies its own line; there are no combined actions. Reading flow: Methods follow a natural peek-next-remove sequence, with consistent formatting. Minor distractions include the wrapped Javadoc link and lack of blank lines separating the package declaration and import groups.