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 load();
/**
* {@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 send();
/**
* {@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 choose();
}
Run 1
The code is well-structured as an interface with clear Javadoc, but readability is significantly harmed by misleading method names: 'load', 'send', and 'choose' do not reflect their actual behavior as 'peek', 'next', and 'remove'. This obscures intent and forces readers to rely on documentation. Structure and flat nesting are good, and action granularity is fine. However, the odd naming, redundant/inconsistent nullness annotations, and verbose Javadoc for simple methods reduce clarity and reading flow. Concise but confusing.
Run 2
The code is highly readable: it has a clear, logical interface structure with well-organized Javadoc. Nesting is minimal (none), and intent is unambiguous through descriptive method names and documentation. Action granularity is appropriate, with one annotation or declaration per line improving scanability. Reading flow is natural, following standard Java conventions. However, the method names ('load', 'send', 'choose') appear to be placeholders or obfuscated names that contradict the documentation (which refers to 'peek', 'next', 'remove'), slightly reducing clarity of intent. Otherwise, the code is concise and well-structured.
Run 3
The code is heavily obfuscated: 'load', 'send', and 'choose' replace 'peek', 'next', and 'remove', making the intent completely unclear relative to the documented PeekingIterator contract. Structure and indentation are fine, and nesting is absent, but clarity of intent is severely damaged by misleading naming. Action granularity is appropriate, but the reading flow is unnatural because the method names contradict their Javadoc and inherited semantics. The class is also suspiciously minimal for an interface with such misleading vocabulary, suggesting deliberate or accidental corruption. While formatting and brevity are acceptable, the core purpose is ambiguous and confusing, making the code hard to read and maintain in practice.
Run 1
Code Structure: The interface is logically organized, with imports, type documentation, and individually documented methods. Nesting: Flat declarations make scanning easy. Clarity of intent: Significantly weakened by method names load(), send(), and choose(), which conflict with documentation describing peek(), next(), and remove(). The @Override annotations on send() and choose() also contradict Iterator's method contracts. Code length: Reasonably concise, though extensive documentation becomes distracting because it describes different methods. Action granularity: Each declaration and annotation occupies its own line; there are no bundled actions. Reading flow: Conventional Java layout provides a natural sequence, but repeatedly reconciling names, documentation, and inheritance interrupts comprehension.
Run 2
Code Structure: The interface is logically organized, with imports, class documentation, and individually documented methods. Nesting: There is no deep nesting, making the declarations easy to scan. Clarity of intent: Significantly weakened by method names load(), send(), and choose(), which conflict with documentation describing peek(), next(), and remove(). The @Override annotations on send() and choose() are also inconsistent with Iterator's methods, making the intended contract confusing. Code length: The interface is concise, although documentation occupies most of the snippet. Action granularity: Each declaration and annotation is on its own line; there are no bundled operations. Reading flow: Formatting and method ordering are natural, but repeated references to undeclared methods interrupt comprehension and undermine otherwise clear documentation.
Run 3
Code Structure: The interface is logically organized with grouped imports and separately documented methods. Nesting: There is no deep nesting, making the layout easy to scan. Clarity of intent: Significantly weakened by method names load(), send(), and choose(), which conflict with documentation describing peek(), next(), and remove(). The @Override annotations on send() and choose() also contradict Iterator's API, creating confusion. Code length: Declarations are concise, though extensive documentation becomes distracting because it describes different methods. Action granularity: Each declaration and annotation occupies its own line, supporting readability. Reading flow: Formatting and method separation are consistent, but mismatches between names, documentation links, and inherited contracts repeatedly interrupt comprehension.