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 has a clear, logical structure as an interface with well-organized method declarations grouped by functionality. Nesting is effectively zero, with only the package and import statements providing minimal external structure. Intent is clearly expressed through descriptive method names and Javadoc comments that explain complex behavior (e.g., undirected self-loop handling). The code is concise, with no unnecessary verbosity. Action granularity is appropriate—each method signature is self-contained and follows a one-action-per-line pattern. Reading flow is natural, progressing logically from basic accessors to more complex mutation methods. Minor deductions: a few Javadoc comments could be slightly more detailed, but this does not significantly impact overall readability.
Run 3
The code is highly readable. Structure is logical with grouped related methods and clear Javadoc on non-obvious methods. Nesting is nonexistent — only top-level interface methods and imports. Intent is clear: it defines an interface for graph connection operations, with parameter names and method names accurately reflecting behavior. Length is concise; each method is necessary and no extraneous code exists. Action granularity is one declaration per line, improving scanability. Reading flow is natural: type params, method groups, and documentation follow a consistent, predictable order. Minor deductions: lack of blank lines between method groups could slightly improve visual separation, and a few methods (e.g., `addInEdge`) lack full documentation for the `isSelfLoop` parameter, leaving minor ambiguity.
Run 1
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 type documentation, and focused comments explain the purpose and directed/undirected distinctions. Nullability and return-value annotations clarify contracts. Code length: The interface is concise, with documentation adding useful context rather than unnecessary length. Action granularity: Each declaration occupies its own logical unit, with no combined operations. Reading flow: Consistent formatting and query-before-mutation ordering make it easy to scan. Minor limitations include undocumented basic query methods and an unexplained isSelfLoop parameter on addInEdge.
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 make scanning easy. Clarity of intent: Descriptive method names, generic types, and targeted documentation explain responsibilities and directed versus undirected behavior; the isSelfLoop parameter on addInEdge could use explicit documentation. Code length: Concise declarations and useful comments avoid unnecessary verbosity. Action granularity: Each method declaration occupies its own line and expresses a distinct operation. Reading flow: Consistent formatting and query-before-mutation ordering create a natural progression, although a blank line after the package declaration would improve visual separation.
Run 3
Code Structure: The interface logically groups node queries, edge queries, and mutation methods. Nesting: Flat method declarations avoid nested control flow entirely. Clarity of intent: Descriptive names, generic types, and focused Javadoc clearly communicate purpose; annotations clarify nullability and return-value usage. Minor gaps include undocumented basic query methods and limited explanation of isSelfLoop in addInEdge. Code length: Concise declarations and relevant documentation avoid unnecessary verbosity. Action granularity: Each declaration occupies its own line and represents one operation. Reading flow: Consistent formatting and progression from queries to removals and additions make the interface easy to scan.