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 is a clean interface definition with a logical grouping of related methods (adjacency, edges, modifications). Nesting is effectively flat. Intent is clearly expressed through descriptive method names and concise Javadoc comments. The code is concise without being overly dense. Most methods are single-action declarations. Reading flow is natural, progressing from general queries to specific modifications. The only minor deductions are for a few method names that could be slightly more explicit and the inherent brevity of interface declarations.
Run 3
The code is highly readable, with clear logical organization as a well-defined interface. It uses flat nesting with no conditional or loop structures. Each method has a clear purpose, supported by concise Javadoc comments. The methods are short and focused, maintaining single-action granularity. The reading flow is natural and intuitive, grouping related methods (adjacent nodes, edges, in/out operations) in a logical order. Minor deductions are due to the slightly verbose Javadoc for straightforward methods, but overall clarity remains excellent.
Run 1
Code Structure: The interface logically groups node queries, edge queries, and mutation methods. Nesting: There is no nested control flow, making the declarations easy to scan. Clarity of intent: Descriptive method names, generic types, annotations, and focused Javadoc clearly communicate purpose and important directed/undirected behavior. Minor gaps include undocumented basic queries and limited explanation of isSelfLoop in addInEdge. Code length: The interface is concise, with documentation adding useful context rather than unnecessary bulk. Action granularity: Each declaration describes a single operation; annotations are clearly associated with their methods. Reading flow: Consistent formatting and progression from inspection to mutation support natural reading, although explicit grouping comments could improve navigation slightly.
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 focused Javadocs make the contract clear; directed-edge assumptions and nullable results are explicitly documented. Code length: Declarations and comments are concise without unnecessary repetition. Action granularity: Each method declaration occupies its own line and represents a focused operation. Reading flow: Consistent spacing and ordering support easy scanning from queries to mutations. Minor shortcomings include missing documentation for the initial query methods and limited explanation of the isSelfLoop parameter on addInEdge.
Run 3
Code Structure: The interface logically groups node queries, edge queries, removals, and additions. Nesting: It is flat, with no nested control flow. Clarity of intent: Descriptive method names, generic types, annotations, and targeted Javadoc make the contract clear; however, several query methods lack documentation, and the addInEdge self-loop parameter is not explained. Code length: The interface is concise, with useful rather than excessive comments. Action granularity: Each declaration expresses a single operation, with no bundled statements. Reading flow: Consistent formatting and progression from inspection to mutation support natural reading, though a blank line after the package declaration would improve separation.