Source code
package com.google.common.graph;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.util.Set;
import org.jspecify.annotations.Nullable;
/**
* An interface for representing and manipulating an origin node's adjacent nodes and incident edges
* in a {@link Network}.
*
* @author James Sexton
* @param <N> Node parameter type
* @param <E> Edge parameter type
*/
interface NetworkConnections<N, E> {
Set<N> adjacentNodes();
Set<N> predecessors();
Set<N> successors();
Set<E> incidentEdges();
Set<E> inEdges();
Set<E> outEdges();
/**
* Returns the set of edges connecting the origin node to {@code node}. For networks without
* parallel edges, this set cannot be of size greater than one.
*/
Set<E> edgesConnecting(N node);
/**
* Returns the node that is adjacent to the origin node along {@code edge}.
*
* <p>In the directed case, {@code edge} is assumed to be an outgoing edge.
*/
N adjacentNode(E edge);
/**
* Remove {@code edge} from the set of incoming edges. Returns the former predecessor node.
*
* <p>In the undirected case, returns {@code null} if {@code isSelfLoop} is true.
*/
@CanIgnoreReturnValue
@Nullable N removeInEdge(E edge, boolean isSelfLoop);
/** Remove {@code edge} from the set of outgoing edges. Returns the former successor node. */
@CanIgnoreReturnValue
N removeOutEdge(E edge);
/**
* Add {@code edge} to the set of incoming edges. Implicitly adds {@code node} as a predecessor.
*/
void addInEdge(E edge, N node, boolean isSelfLoop);
/** Add {@code edge} to the set of outgoing edges. Implicitly adds {@code node} as a successor. */
void addOutEdge(E edge, N node);
}
Run 1
The code demonstrates excellent readability through its clean logical structure and intuitive organization. The interface groups related methods together (adjacency queries, edge queries, then mutations), creating a natural reading flow. Nesting is non-existent, resulting in a flat, easily scannable structure. The intent is highly clear from both the method names and concise Javadoc comments that accurately document behavior, including edge cases like self-loops and directed vs undirected semantics. Code length is appropriate—each method is essential to the abstraction, and comments add value without redundancy. Action granularity is impeccable: each method declaration occupies its own logical unit, and the interface overall maintains one purpose per method. The generic type parameters are consistently named and documented. While slightly dense due to the volume of methods, the consistent organization and clear documentation make this interface exemplary in readability, justifying a high score rather than perfect marks only because dense interfaces can tax comprehension without implementation context.
Run 2
The code is a well-structured Java interface with clear purpose and organization. Methods are logically grouped: adjacency queries first, then edge-specific operations, then mutating methods. Nesting is non-existent, as expected for an interface. Each method has a concise, explicit name and Javadoc comments clarify intent, especially for non-obvious behaviors like self-loops or directed edge assumptions. Code length is appropriate—no redundancy or over-engineering. Action granularity is excellent, with one method per line and no multiple operations crammed together. Reading flow is natural: imports are minimal, the type parameters are documented, and method ordering follows a logical progression from general queries to specific mutations. Minor deductions: some Javadoc could be slightly more detailed (e.g., `removeOutEdge` return value in undirected case), and annotations like `@CanIgnoreReturnValue` add slight visual noise, but overall readability is high.
Run 3
The code is exceptionally readable and well-structured. It defines a clear, cohesive interface with logically grouped methods for accessing adjacent nodes, predecessors, successors, and edge sets. Nesting is non-existent, as it is a flat interface definition. Method names and Javadoc make the intent unambiguous—e.g., distinguishing in/out edges, handling self-loops, and clarifying undirected behavior. The code is concise without being cryptic, and each method declaration is a single action per line, enhancing clarity. The reading flow is natural: related methods are grouped, and documentation precedes more complex methods to explain nuances. Minor deductions could be argued for the slightly verbose Javadoc, but this rarely counts against readability in a library context.
Run 1
Code Structure: Logically groups node queries, edge queries, and mutation methods within a focused interface. Nesting: No nested control flow; declarations are flat and easy to scan. Clarity of intent: Descriptive method names, generic type documentation, and targeted comments explain directionality and special cases. The isSelfLoop parameter on addInEdge could benefit from explicit documentation. Code length: Concise, with useful comments rather than unnecessary verbosity. Action granularity: Each method declaration occupies its own line, with annotations clearly associated with the relevant method. Reading flow: Proceeds naturally from inspection to modification, though separating the package declaration from imports with a blank line would improve formatting.
Run 2
Code Structure: Methods are logically grouped into node queries, edge queries, removals, and additions. Nesting: The interface is flat, with no nested control flow. Clarity of intent: Descriptive method names, generic type documentation, and targeted Javadoc make the purpose clear; the undocumented basic queries and addInEdge's isSelfLoop parameter leave minor semantic gaps. Code length: Concise declarations and useful comments avoid unnecessary verbosity. Action granularity: Each declaration occupies its own line, with annotations clearly associated with methods. Reading flow: Consistent spacing and ordering create a natural progression from inspection to modification. A blank line after the package declaration would slightly improve visual separation.
Run 3
Code Structure: Logically groups node queries, edge queries, removals, and additions in a compact interface. Nesting: Flat declarations with no nested control flow. Clarity of intent: Descriptive method names and focused Javadoc explain purpose, directionality, and special cases; the role of isSelfLoop in addInEdge could be documented more explicitly. Code length: Concise, with comments that add useful context rather than redundancy. Action granularity: Each declaration represents a single operation, with annotations clearly attached to relevant methods. Reading flow: Consistent formatting and progression from queries to mutations make the interface easy to scan. Minor omissions in documentation prevent a perfect score.