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 presents a clean interface with clear separation of concerns: getters for structural queries (adjacentNodes, predecessors, etc.) are grouped together before mutating operations (removeInEdge, addOutEdge, etc.). Nesting is essentially flat, with the only meaningful structure being the class-level declaration. Each method has a clear purpose, and the javadoc comments effectively clarify intent, especially for edge cases like self-loops and directed vs undirected behavior. The code is concise—no unnecessary boilerplate or long methods. Action granularity is excellent, with one logical operation per method declaration. Reading flow is natural: a reader can scan the getter methods first to understand the data model, then move to the mutators to understand supported operations. The only minor nitpick is that some method names and parameters (e.g., removeInEdge with isSelfLoop) require reading the javadoc to fully grasp, but this is reasonable for a low-level API.
Run 3
The code is exceptionally readable. The interface is logically structured, grouping related methods (adjacent nodes, edges, modifications) with clear separation. Nesting is nonexistent due to the flat interface declaration. Intent is clearly conveyed through descriptive method names and concise Javadoc comments, especially for ambiguous operations like removeInEdge and addInEdge. The code is concise, with no unnecessary boilerplate or redundant annotations. Each method declaration occupies a single line, and import statements are minimal and purposeful. Reading flow is natural: the interface starts with basic accessors, progresses to edge-specific queries, and ends with mutators, mirroring a typical mental model. The use of generic types and nullability annotations enhances clarity without clutter. Only minor areas for potential improvement include grouping methods into sub-interfaces if the interface grows, but as is, it is nearly ideal.
Run 1
Code Structure: The interface logically groups node queries, edge queries, and mutation methods. Nesting: Completely flat aside from the interface scope, making it easy to scan. Clarity of intent: Descriptive method names, generic type documentation, and targeted Javadocs explain purpose and directed versus undirected behavior. Nullability and return-value annotations clarify contracts. Code length: Concise declarations with useful rather than excessive documentation. Action granularity: Each method declaration occupies its own line, with no combined operations. Reading flow: Consistent formatting and progression from queries to mutations support natural reading. Minor limitations include undocumented basic query methods and the lack of an explicit explanation of isSelfLoop for addInEdge.
Run 2
Code Structure: The interface logically groups node queries, edge queries, removals, and additions. Nesting: Flat method declarations with no nested control flow make scanning easy. Clarity of intent: Descriptive method names, generic type documentation, and targeted Javadocs explain purpose and important directed/undirected behavior; the isSelfLoop parameter on addInEdge could use explicit documentation. Code length: Concise declarations and relevant comments avoid unnecessary verbosity. Action granularity: Each method declaration occupies its own line and represents a focused operation. Reading flow: Consistent spacing and annotations support a natural progression from inspection to mutation, though the initial query methods lack documentation and the package/import section could benefit from a separating blank line.
Run 3
Code Structure: The interface logically groups node queries, edge queries, and mutation methods. Nesting: It is flat, with no nested control flow. Clarity of intent: Descriptive method names, generic types, and targeted documentation make its purpose clear; the initial query methods lack documentation, and addInEdge does not explain isSelfLoop. Code length: Declarations and comments are concise without unnecessary boilerplate. Action granularity: Each method declaration represents a distinct operation, with no packed statements. Reading flow: Consistent formatting and progression from queries to removals and additions support easy scanning. A blank line after the package declaration would slightly improve visual separation.