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 generally well-structured with clear documentation and logical organization. The interface is concise and purposeful, with good use of annotations and Javadoc. However, there are some readability issues: multiple import statements are compressed onto single lines, and class-level annotations are appended to the end of the Javadoc block rather than on separate lines. The closing brace shares a line with the final method, which slightly disrupts the reading flow. The method declarations are appropriately flat with no nesting, and each action is clearly separated. The Javadoc is thorough but well-formatted. Overall, the code is readable but would benefit from more consistent line breaks and formatting, particularly around imports and annotations.
Run 2
The code is highly readable overall. Structure is logical with clear separation between interface declaration, annotations, and method definitions. Javadoc is thorough and well-formatted, adding significant clarity. Nesting is essentially flat — the interface has no nested blocks. Intent is unambiguous: a peeking iterator with clear behavioral contracts. Action granularity is mostly one action per line, though a few lines combine annotations (e.g., '@Override void remove();' and the interface-level annotations). Reading flow is natural: imports, documentation, declaration, then methods. Minor deductions: multiple imports on one line (admittedly common in Java), some annotation stacking on single lines, and the class-level annotations placed after the Javadoc slightly disrupt visual separation. Overall, excellent clarity and organization.
Run 3
The code is generally well-structured and readable: clear interface definition, good use of Javadoc, and natural method ordering (peek, next, remove). However, readability is negatively impacted by inconsistent formatting in the imports section (multiple imports on one line) and annotations placed on the same line as declarations rather than on separate lines. The Javadoc is comprehensive and clarifies intent, but the method signature annotations are cramped on a single line, reducing scanability. Nesting is minimal and clarity of intent is strong; the main issues are typographic spacing and line-break consistency, which slightly disrupt natural reading flow.
Run 1
1. Code Structure: The interface logically groups three related iterator methods, with documentation attached to each. 2. Nesting: No nested control flow; the interface is flat and easy to scan. 3. Clarity of intent: Descriptive names and detailed Javadoc clearly explain lookahead behavior and removal constraints. 4. Code length: Concise declarations; documentation adds useful contract details rather than unnecessary bulk. 5. Action granularity: Multiple imports on one line and annotations, declarations, and the closing brace sharing lines reduce visual separation. 6. Reading flow: Method order is natural, but compressed formatting around the interface annotations and remove() interrupts an otherwise clean reading flow.
Run 2
Code Structure: The interface is logically organized into peek, next, and remove declarations, each with relevant documentation. Nesting: There is no deep nesting or complex control flow. Clarity of intent: Descriptive names and detailed contracts clearly explain lookahead behavior and removal restrictions. Code length: The interface is concise; its documentation is substantial but useful rather than unnecessarily long. Action granularity: Several imports share one line, and some annotations, declarations, and closing braces are compressed together, reducing scanability. Reading flow: Method ordering is natural, but inconsistent formatting, annotations appended to documentation endings, and the final inline closing brace interrupt an otherwise clear presentation.
Run 3
Code Structure: The interface is logically organized around peek(), next(), and remove(), with relevant documentation grouped with each method. Nesting: There is no deep nesting, making the code easy to scan. Clarity of intent: Descriptive method names and precise Javadoc clearly explain lookahead behavior and removal constraints. Code length: The interface is concise; its documentation is longer than the declarations but provides useful contract details. Action granularity: Multiple imports on one line and annotations, declarations, and closing braces compressed together reduce readability. Reading flow: Method ordering is natural, but inconsistent line breaks and annotations appended to comment endings interrupt the otherwise clear flow.