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
This interface is highly readable and well-structured. The code organization is logical, with method declarations grouped into sections (adjacent nodes, incident edges, edge operations) and separated by whitespace. Nesting is minimal - only the class/interface declaration and method bodies are nested, making the code flat and easy to scan. Intent is crystal clear through descriptive method names and purposeful Javadoc comments that explain each method's behavior and edge cases. The code length is concise - no unnecessary boilerplate or redundant annotations. Action granularity is appropriate for an interface, with each method declaration on its own line. Reading flow is natural, moving from basic accessor methods to more complex edge operations in a progressive manner. The only minor deduction is for the slightly verbose Javadoc on some methods, but this actually enhances understanding rather than hindering readability. Overall, this is exceptionally clean, well-documented Java code.
Run 2
The code is highly readable. It has a clear, logical structure as an interface defining graph connection operations. Nesting is minimal, with only concise Javadoc paragraphs. Intent for each method is clear from naming and documentation. Code length is appropriately concise for an interface. Each method declaration is one action per line, following consistent formatting. Reading flow is natural, progressing from simple accessors to more complex edge manipulation methods. Minor improvements could include grouping related methods (e.g., in/out pairs) with blank lines, but overall this is exemplary readable code.
Run 3
The code is highly readable. It has a clear, logical structure as an interface with well-separated method declarations. Nesting is minimal to nonexistent. The intent of each method is made clear through descriptive names and concise Javadoc comments. Code length is appropriate for the functionality, with no unnecessary repetition. Each action is granular and focused, following the single responsibility principle at the method level. The reading flow is natural: generic type parameters and imports come first, followed by a summary of node-edge relationships (adjacent, predecessor/successor, incident) and then specific edge operations. While the interface itself is clean, a minor deduction is made because some methods like `removeInEdge` and `addInEdge` involve boolean flags (`isSelfLoop`) that could slightly reduce clarity without deeper context, though the Javadoc mitigates this.
Run 1
Code Structure: The interface logically groups node queries, edge queries, and mutation operations. Nesting: No nested control flow; declarations remain flat. Clarity of intent: Descriptive method names, generic type documentation, and focused Javadocs make the purpose clear, including directed-edge and self-loop behavior. Code length: Concise, with useful comments rather than redundant explanation. Action granularity: Each method declaration represents one operation, with annotations clearly separated where appropriate. Reading flow: The progression from queries to removals and additions is natural, supported by consistent spacing. Minor limitations include undocumented semantics for basic query methods and the isSelfLoop parameter on addInEdge.
Run 2
Code Structure: The interface logically groups node queries, edge queries, removals, and additions. Nesting: The structure is flat, with no nested control flow. Clarity of intent: Descriptive method names, generic types, annotations, and targeted documentation clearly express responsibilities and return behavior; the meaning of isSelfLoop in addInEdge could be documented more explicitly. Code length: Declarations and comments are concise, with little redundancy. Action granularity: Each declaration occupies its own line and represents a single operation. Reading flow: Consistent formatting and progression from queries to mutations make the interface easy to scan, though separating the package declaration from imports with a blank line would improve presentation.
Run 3
Code Structure: The interface logically groups node queries, edge queries, removals, and additions. Nesting: Declarations are flat, with no nested control flow. Clarity of intent: Descriptive method names, generic type documentation, and focused comments make the purpose clear; annotations communicate nullability and return-value expectations. Some query methods lack documentation, and addInEdge does not explain isSelfLoop. Code length: Concise declarations and relevant comments avoid unnecessary verbosity. Action granularity: Each method declaration occupies its own line and expresses a distinct operation. Reading flow: Consistent formatting and progression from queries to mutations make scanning natural, though spacing between the package and imports would improve presentation.