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> adjacent();
Set<N> pre();
Set<N> suc();
Set<E> incident();
Set<E> in();
Set<E> out();
/**
* 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> edges(N nod);
/**
* 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 adjacent2(E edg);
/**
* 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 remove(E edg2, boolean is);
/** Remove {@code edge} from the set of outgoing edges. Returns the former successor node. */
@CanIgnoreReturnValue
N remove2(E edg3);
/**
* Add {@code edge} to the set of incoming edges. Implicitly adds {@code node} as a predecessor.
*/
void add(E edg4, N nod2, boolean is2);
/** Add {@code edge} to the set of outgoing edges. Implicitly adds {@code node} as a successor. */
void add2(E edg5, N nod3);
}
Run 1
The code is well-structured and organized as an interface, with method names that generally convey intent (e.g., adjacent, incident, in, out, remove, add). Documentation is helpful for most methods, and the overall length is concise with flat structure. However, readability is hindered by inconsistent and abbreviated parameter names like 'nod', 'edg', 'edg2', 'is', 'nod2', 'is2', 'edg3', 'edg4', 'edg5', and 'nod3'. These names are ambiguous and force the reader to rely on comments to understand what each parameter represents. The method names 'adjacent2', 'remove2', and 'add2' also lack clarity, as the '2' suffix does not convey meaning without inspecting the corresponding comment. This reduces the self-documenting quality of the code and hurts the natural reading flow.
Run 2
The code has a clear overall structure as an interface with logically grouped methods, and the method declarations are concise with one action per line. However, readability suffers from poor naming choices: method names like 'adjacent2', 'add2', 'remove2' obscure intent, and parameters like 'nod', 'edg', 'is' are ambiguous abbreviations. The method signatures do not explain the difference between 'remove' and 'remove2' without reading the docs, and 'is'/'is2' parameters are especially unclear. Some Javadoc is present but lacks consistency and detail for several methods. Nesting is flat, which is good, and the reading flow is acceptable, but the unclear naming and vague parameters significantly reduce overall readability. The code could be improved with descriptive names such as 'adjacentNodeViaEdge', 'removeIncomingEdge', and boolean parameters like 'isSelfLoop'.
Run 3
The code is generally readable but has some flaws. The interface has clear purpose and logical structure, with methods organized by adjacent, incident, in/out, and edge manipulation. However, parameter names are poor: 'nod', 'edg', 'edg2', 'edg3', 'edg4', 'edg5', 'nod2', 'nod3', 'is', 'is2' are cryptic and reduce clarity. Javadoc quality is inconsistent—some methods have no documentation (adjacent(), pre(), suc(), incident(), in(), out()), while others have overly brief or vague docs. Method names like 'adjacent2()', 'remove2()', 'add2()' are ambiguous and don't clearly convey intent. The interface is concise (good), not deeply nested, and action granularity is fine. Overall structure is sound but naming significantly impacts readability.
Run 1
Code Structure: The interface is logically organized, grouping node queries, edge queries, removals, and additions. Nesting: There is no nested control flow, making the code easy to scan. Clarity of intent: The main weakness is ambiguous naming, including pre, suc, adjacent2, remove2, and add2, alongside cryptic parameters such as edg4 and is2. Documentation helps explain behavior, but its parameter references do not match the actual names, reducing clarity. Code length: The interface is concise, with little unnecessary content. Action granularity: Each method declaration occupies a separate line, cleanly separating operations. Reading flow: Consistent formatting and method grouping support natural reading, but readers must repeatedly consult comments to distinguish incoming and outgoing operations.
Run 2
Code Structure: The interface is logically organized, grouping adjacency queries, edge queries, removals, and additions. Nesting: Flat declarations with no nested control flow make scanning easy. Clarity of intent: The main weakness is abbreviated or numbered names such as pre, suc, adjacent2, remove2, edg4, and is2. Documentation helps explain operations, but references to edge, node, and isSelfLoop do not match actual parameter names, reducing clarity. Code length: Concise and appropriate for an interface, without unnecessary implementation detail. Action granularity: Each method declaration represents a single operation, and annotations are clearly separated. Reading flow: Consistent spacing and query-before-mutation ordering support natural reading, but ambiguous names force readers to consult comments repeatedly.
Run 3
Code Structure: The interface logically groups adjacency queries and edge mutations, with consistent formatting. Nesting: It is flat, with no nested control flow. Clarity of intent: The main weakness is abbreviated and numbered names such as pre, suc, adjacent2, remove2, edg4, and is2. These obscure distinctions between incoming and outgoing operations. Documentation helps, but references parameter names such as edge, node, and isSelfLoop that do not match the declarations. Code length: The interface is concise without obvious redundancy. Action granularity: Each declaration occupies its own line and represents a single operation. Reading flow: Query methods followed by mutation methods provide a natural sequence, but ambiguous names and mismatched documentation force readers to infer meaning.