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-documented interface with logical method grouping—adjacency, edges, and mutation operations are cleanly separated. Nesting is absent as it is an interface, and each method declaration is concise, typically fitting on one line. Javadoc comments clarify intent, especially for nuanced behaviors like self-loops and edge directionality. Method names are descriptive and align with graph theory terminology, enhancing clarity. The annotations (@CanIgnoreReturnValue, @Nullable) further improve understanding of method contracts. The code avoids unnecessary length while maintaining completeness. Overall, structure and flow are natural and easy to follow. Minor deductions are due to slight repetition in method documentation patterns, but this does not meaningfully affect readability.
Run 3
This code is highly readable due to its clean structure and clear purpose. The interface is logically organized with all getter methods grouped together first, followed by mutator methods. There is minimal nesting — only a single level for the interface and its method declarations. Each method has a clear, descriptive name that conveys its intent, and concise Javadoc comments clarify ambiguous behavior (e.g., directed vs undirected cases). Code length is appropriate, with no unnecessary verbosity. Each method declaration occupies a single line, maintaining good action granularity. The reading flow is natural and intuitive, progressing from general accessors to specific edge operations. Minor potential improvements could include adding Javadoc for every method, but overall readability is excellent.
Run 1
Code Structure: The interface logically groups node queries, edge queries, and mutation methods. Nesting: Flat method declarations have no nested control flow. Clarity of intent: Descriptive names, generic types, annotations, and focused documentation clearly express purpose and important directed/undirected behavior. Code length: Concise declarations and relevant comments avoid unnecessary verbosity. Action granularity: Each declaration occupies its own line, with annotations clearly separated. Reading flow: Consistent formatting and progression from queries to mutations make scanning natural. Minor drawbacks are the undocumented basic query methods and the unexplained isSelfLoop parameter on addInEdge.
Run 2
Code Structure: The interface logically groups node queries, edge queries, and mutation methods. Nesting: The structure is flat, with no nested control flow. Clarity of intent: Descriptive method names, generic type documentation, and focused Javadocs clearly communicate purpose; annotations clarify nullability and return-value handling. Code length: Declarations and comments are concise without unnecessary implementation detail. Action granularity: Each method declaration occupies its own line and represents a focused operation. Reading flow: Consistent formatting and progression from queries to mutations make the interface easy to scan. Minor limitations are the lack of documentation for the initial query methods and limited explanation of the isSelfLoop parameter in addInEdge.
Run 3
Code Structure: The interface logically groups node queries, edge queries, removals, and additions. Nesting: Flat method declarations have no nested control flow. Clarity of intent: Descriptive method names, generic types, annotations, and targeted documentation make the contract clear, though 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 separated where appropriate. Reading flow: Consistent formatting and query-before-mutation ordering support natural reading; a blank line after the package declaration would slightly improve visual separation.