Understanding Code Health
A practical guide to what gdhealth measures, what to do next, and what results cannot prove.
Understanding code health
gdhealth helps you decide where to look first. It reads GDScript text; it does not run your game or prove code is broken. Treat a high score as a priority signal, then use judgement.
The six questions
- Scope — files and code size: How much code exists? Observe growth and act when ownership or review becomes difficult.
- Code shape — functions, branches, nesting, and parameters: How hard is this code to understand and test? Schedule simplification for high control-flow load.
- Coupling — dependencies, fan-in, fan-out, and cycles: What else can affect this code, or be affected by it? Act now on harmful cycles; schedule unusually broad fan-out.
- Priority — hotspot and Git churn: Where is improvement likely to pay off? A hotspot that changes often is a strong improvement candidate.
- Evidence — policies, duplicate code, and unresolved references: What concrete evidence needs review? Act on critical findings; observe expected dynamic references.
- Contracts and events — signals, exports, RPC, groups, InputMap, and node bindings are runtime capabilities, not automatic problems.
Dependencies: pairs and relationships
A connected file pair is one source-file → target-file connection after graph filters. A declared relationship is each static occurrence. If ui.gd both extends and preloads base.gd, that is one pair and two relationships.
Declaring signal died is not an edge: it says the file can emit a signal. gdhealth draws a line only when it can statically identify both endpoints of a use. Dynamic loads and unknown signal receivers remain diagnostics so the graph does not invent links.
Examples and response guide
- High fan-in:
inventory.gdis used by 18 files. Change it carefully: many callers may be affected. - High fan-out:
gameplay_controller.gdreferences 20 files. Consider whether it owns too many responsibilities. - High control-flow load: many branches and nested loops make paths harder to test. Split decisions into focused functions.
- Hotspot: a large, connected file that changes often is likely to repay improvement work.
Act now: critical policy findings, unexpected cycles, and unresolved targets blocking an architecture decision. Schedule: persistent hotspots, difficult control flow, large files, and repeated duplicates. Observe: warnings and deliberately shared services. Ignore intentionally: generated code and documented dynamic loading, after recording why.
Limits
Analysis is text-based. Dynamic runtime paths, scene wiring, generated code, and values assembled at runtime may be absent or unresolved. Scores compare files in one report; they are not defect predictions or universal quality grades.
Glossary
- SLOC: source lines of code.
- Dependency: one file statically references another.
- Relation: one occurrence of a recognized dependency kind.
- Coupling: how strongly code is connected to other code.
- Cycle: files depend on one another in a loop.
- Cluster: files more connected to each other than to the rest of the graph.
- Policy finding: a configured rule was exceeded.
- Hotspot: a relative ranking combining code difficulty and coupling.
- Unresolved target: a possible use whose endpoint could not be proven statically.