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 defines a clear, well-structured interface with logically grouped methods for querying and modifying network connections. The class-level and method-level Javadoc comments effectively explain purpose and important semantics, especially for edge cases like self-loops and directed/undirected behaviors. Each method performs a single, well-defined action, and the method declarations are concise and not nested. Imports and package declaration are standard, and method ordering flows naturally from querying to mutation. The only minor deductions are for slightly terse method documentation on some mutating methods and the inherent complexity of the domain model, but overall this is exemplary code clarity.
Run 3
The code is highly readable due to its clear structure, minimal nesting, and concise methods with strong documentation. Each method has a distinct, focused purpose, and the use of Javadoc clearly communicates intent, especially for edge cases like self-loops. The interface is logically organized, grouping related methods like predecessors/successors and in/out edges, with no unnecessary complexity. While the code is fairly dense, it remains easy to scan, and the annotations add useful context without cluttering the logic.
Run 1
Code Structure: Methods are logically grouped into node queries, edge queries, and mutation operations. Nesting: No nested control flow; the interface is flat and easy to scan. Clarity of intent: Descriptive method names, generic types, annotations, and targeted documentation clearly communicate purpose and return behavior. The isSelfLoop parameter on addInEdge could use explicit documentation. Code length: Concise, with useful comments rather than unnecessary verbosity. Action granularity: Each declaration occupies its own line and represents a focused operation. Reading flow: Consistent formatting and progression from queries to mutations support natural reading, though a blank line after the package declaration would improve visual separation.
Run 2
Code Structure: Logically groups node queries, edge queries, removals, and additions within a focused interface. Nesting: Flat declarations with no nested control flow. Clarity of intent: Descriptive method names, generic types, and targeted documentation clearly convey responsibilities; self-loop behavior for addInEdge could be documented more explicitly. Code length: Concise, with useful comments and no unnecessary implementation detail. Action granularity: Each declaration occupies its own line and represents one operation. Reading flow: Consistent spacing and progression from queries to mutations make scanning natural, though a blank line after the package declaration would improve visual separation.
Run 3
Code Structure: The interface logically groups node queries, edge queries, removals, and additions. Nesting: Flat method declarations introduce no nested control flow. Clarity of intent: Descriptive method names, generic types, and focused documentation communicate purpose well; however, the initial query methods lack documentation, and addInEdge does not explain isSelfLoop. Code length: Concise declarations and relevant comments avoid unnecessary verbosity. Action granularity: Each declaration occupies its own line, with annotations clearly associated with methods. Reading flow: Consistent formatting and progression from queries to mutations make the interface easy to scan, though a blank line after the package declaration would improve visual separation.