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 clean interface named NetworkConnections with clear Javadoc comments explaining each method's purpose. The structure is logical, grouping related methods for adjacency, predecessors/successors, and incident edges. Nesting is non-existent; methods are flat and concise. Each method performs a single, well-defined action. Annotations (@Nullable, @CanIgnoreReturnValue) add clarity without clutter. Parameter names are descriptive, and the generic type parameters are documented. Minor issues include slightly verbose JavaDocs for very simple methods, but this is consistent with library documentation standards. Overall, the code is well-organized, easy to follow, and adheres to strong readability principles.
Run 3
This code is highly readable. It's a clean, well-documented interface with a logical structure: simple getter methods grouped first, followed by mutation methods. The method names clearly express intent (e.g., adjacentNodes, removeInEdge, addOutEdge). The nesting is completely flat, with no control flow to complicate reading. Each method declaration is concise, and documentation is focused and informative, particularly noting edge cases like self-loops and parallel edges. While the interface is somewhat long due to many methods, each is necessary and follows a consistent pattern. The use of @CanIgnoreReturnValue and @Nullable annotations enhances clarity. Reading flow is natural, moving from basic queries to more complex operations. Minor deductions only for slight verbosity in comments, but overall this is exemplary interface design.
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, and focused documentation clearly communicate purpose; the isSelfLoop parameter on addInEdge could use explicit documentation. Code length: The interface is concise, with comments adding useful context rather than repetition. Action granularity: Each method declaration occupies its own line, and annotations are clearly associated with their methods. Reading flow: The progression from queries to removals and additions is natural, with consistent spacing and formatting. Minor improvements would include documenting the initial query methods' contract details and separating the package declaration from imports.
Run 2
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 and focused Javadoc explain operations, directionality, and special cases; the undocumented basic queries and addInEdge's isSelfLoop parameter leave minor gaps. Code length: Concise declarations and relevant documentation avoid unnecessary verbosity. Action granularity: Each declaration occupies its own line and represents a single operation. Reading flow: Consistent formatting and query-before-mutation ordering make the interface easy to scan, though spacing between the package and imports would slightly improve visual separation.
Run 3
Code Structure: The interface logically groups node queries, edge queries, and mutation methods. Nesting: Flat declarations with no nested control flow make scanning easy. Clarity of intent: Descriptive method names and focused Javadoc explain purpose, directionality, and special cases; the undocumented query methods and addInEdge's isSelfLoop parameter leave minor gaps. Code length: Concise signatures and useful documentation avoid unnecessary verbosity. Action granularity: Each declaration occupies its own line and represents a focused operation. Reading flow: Consistent spacing and progression from queries to removals and additions support natural reading, although separating the package declaration from imports would slightly improve presentation.