30 Make software understandable beyond source code

Source code describes executable structure, but it rarely contains the whole reason that structure exists. A developer can follow a call graph and still not know which requirement created a boundary, which alternative was rejected, or what evidence supports a claim of readiness.

Connecting code representations with intent, decisions, applied guidance, and other information can help readers understand why software has its present structure. A visual representation should be evaluated through the questions it helps answer, rather than the fact that the result is a graph.

Begin with a question that code alone answers poorly

Consider: “If we change when a candidate becomes ready, which acceptance claims and consumers need review?” A call graph may identify callers. It may not identify a decision record explaining why the current boundary was chosen, or an acceptance observation made through a particular application.

A useful representation could link the readiness decision to its contract, implementation owner, tests, consumers, and evidence. Each edge needs a meaning. “Related to” is too vague if readers use the graph to decide what must be checked.

Another question is historical: “Why did we keep the old version available during preparation?” A source comment may explain it, or the reason may live in a discussion, plan, or failure report. The representation should help retrieve that reason without pretending every historical influence was recorded.

Keep structural and semantic relationships distinct

A code reference is an observed relationship in the implementation. A decision depends on a requirement is a semantic claim. A test supports an acceptance claim is an interpretation of what the test establishes. These edges have different evidence and maintenance needs.

Automatically extracting references can populate one part of the graph. It cannot infer all intent relationships with equal authority. A generated edge may be a useful suggestion, but should remain attributable and revisable.

RepoGraph reports benefits from code-relationship context for evaluated issue-resolution baselines. That is evidence about code retrieval in its setting. It does not validate a broader graph of intent, authority, and decisions. The broader design needs its own evaluation. RepoGraph.

Design for reading rather than displaying everything

A graph containing every node and edge can be less understandable than a short explanation. Readers need entry points, meaningful grouping, filtering, and progressive detail.

For the readiness question, begin with the decision and immediate dependencies. Let the reader expand a consumer or inspect the supporting evidence. Do not force them to navigate the entire repository to answer a bounded question.

Visual position and color should not carry unsupported meaning. A large node may look important even if its size merely reflects code references. A central position may suggest authority when it is only a layout artifact. Explain the encoding and provide a textual path through the same information.

The representation also needs to show missing or stale evidence. An edge tied to an older revision may still be historically useful but should not silently certify the current implementation.

Make the maintenance cost visible

Every semantic relationship must come from somewhere. A person may record it, an agent may propose it, or a tool may derive it under explicit rules. Changes can invalidate it.

If maintaining the graph takes more effort than the questions it answers justify, the system needs a narrower scope. Begin with a small set of valuable relationships rather than an ontology of all development knowledge.

The graph may be a view over existing records rather than another source of truth. That can reduce duplication, provided the underlying records have stable meanings and identities. It also makes it possible to offer alternative views for different readers.

Test comprehension directly

Give a reader a concrete question and observe whether the representation helps them answer it correctly. Measure time if useful, but also inspect what they misunderstood. A fast wrong answer is not improved understanding.

Compare the graph with a simpler baseline: a linked decision record, a searchable index, or a short narrative. The graph should earn its place through the relationship task, not through novelty.

For an exercise, build a tiny map connecting one outcome, one design decision, one implementation boundary, and two pieces of evidence. Mark the provenance of every edge. Ask another developer what would need reconsideration if the outcome changed. Where the map suggests certainty it cannot support, revise the representation.

The aim is software that can be understood and challenged beyond its source text. A visual model is one possible means to that end.