GHC’s Coding Style Is Really a Governance Document

The Glasgow Haskell Compiler is not merely an implementation detail behind Haskell. It is where language theory, compiler engineering, runtime pragmatics, and community process meet in executable form. A page titled coding style may sound like a modest set of formatting preferences, but in a project like GHC, style becomes a philosophy of maintenance: how to make difficult ideas readable enough that they can survive beyond the person who first encoded them.

Thesis

The core argument implicit in GHC’s coding style guidance is that compiler code is a social artifact as much as a technical one. A compiler transforms programs, but a compiler project transforms human reasoning into a durable shared machine. That means style is not cosmetic. It is a form of memory management for the community itself.

GHC has to express concepts from type inference, desugaring, Core transformations, runtime behavior, code generation, and language extension design. The GHC User’s Guide exposes the public surface of that work, while the repository carries the internal machinery that makes those promises real. In such a setting, coding conventions do not simply make patches easier to review. They reduce the cognitive tax paid by every future contributor who must reconstruct why a function exists, what invariants it assumes, and which parts of the compiler pipeline it is allowed to disturb.

Key arguments

The first argument is that consistency is a tool for conserving attention. In a small project, inconsistent layout or naming is usually irritating. In a compiler like GHC, inconsistency is more expensive because the reader is already spending most of their mental budget on semantic detail. When a contributor reads code that manipulates typed intermediate representations, rewrites expressions, or threads diagnostics through a pipeline, each avoidable stylistic surprise competes with the actual problem.

This is why style guidance in mature compiler projects tends to become stricter in spirit even when it is not enforced with absolute rigidity. Formatting, naming, module boundaries, comments, and idioms all act as affordances for future reading. They tell the reader what is ordinary, what is exceptional, and what deserves extra suspicion. In Haskell, where abstraction can be both clarifying and opaque, style also regulates when elegance becomes a burden. A clever point-free expression may be beautiful in isolation, but a compiler codebase often values explicit structure because explicit structure gives later maintainers something to hold onto.

The second argument is that coding style encodes institutional humility. GHC is old enough, influential enough, and technically dense enough that no individual contributor can hold the whole system in their head. The project therefore needs conventions that assume partial understanding. A good style guide says, in effect, write code for someone who understands Haskell but not this corner of GHC, and who may be debugging a regression under pressure years from now.

That humility matters because GHC is also a research vehicle. Haskell’s implementation has absorbed ideas from type theory, optimization research, runtime systems, and language design. The GHC proposals process formalizes part of that evolution, but implementation work still requires translating abstract designs into concrete compiler behavior. Style becomes the bridge between proposal and maintenance. It asks contributors to leave a trail from concept to code, so the implementation can be argued with rather than merely admired.

The third argument is that comments and names are part of the type system of a human organization. Haskell’s static types can rule out many classes of error, but they cannot fully explain intent. A type may tell us that a function maps one representation to another, but it may not tell us why this conversion must happen before a later pass, why a case looks redundant, or why a seemingly simpler abstraction was avoided. In compiler code, these reasons often matter as much as the definitions themselves.

This is where style becomes philosophical. Programming languages are systems of constraints for machines, while coding style is a system of constraints for people. The two interact. A project such as GHC needs machine-checkable correctness, but it also needs patterns of explanation that let humans form justified beliefs about code they did not write.

Supporting evidence

The broader structure of GHC supports this reading. The public GHC GitLab repository contains the compiler, libraries, tests, runtime system, and build machinery. Its scope alone explains why style guidance cannot be reduced to indentation. GHC is a multi-decade technical commons, and commons require norms.

The public documentation also shows the split between interface and implementation. The User’s Guide explains extensions, warnings, optimization flags, profiling, packages, and runtime behavior from the user’s side. The codebase must then preserve the meaning of those features across releases, platforms, and interactions with other extensions. Every internal convention that makes that work easier has practical value.

There is also a tool-chain context. The Haskell ecosystem has formatters and style tools such as Ormolu and Fourmolu, plus editor support through projects like Haskell Language Server. These tools can standardize many surface decisions, but GHC’s problem is larger than formatting. Automated style can arrange syntax, but it cannot decide whether a function is too clever, whether a Note should explain a subtle invariant, or whether an abstraction hides the compiler phase that a reader most needs to see.

That distinction matters. Modern software teams often try to outsource style to formatters, linters, and continuous integration. Those tools are valuable, yet they address only the parts of style that can be cheaply mechanized. In a compiler, the hardest style questions are semantic. They concern the shape of explanation, the visibility of invariants, and the discipline of writing code that makes future disagreement possible.

Implications

For contributors, the implication is that submitting code to GHC is not just an act of implementation. It is an act of translation. One must translate a local fix into the idiom of a shared system, and that means respecting both the Haskell language and the historical texture of the compiler. A patch that works but reads like an isolated private dialect imposes a debt on reviewers and maintainers.

For language implementers more broadly, GHC’s style culture suggests that the boundary between engineering and documentation is thinner than it appears. The most valuable comments in compiler code often do not repeat what the syntax says. They preserve a reason that would otherwise disappear. The famous compiler-maintainer habit of writing explanatory notes near tricky code reflects a deeper truth: in a sufficiently complex system, code alone is rarely a complete account of itself.

For the Haskell ecosystem, the lesson is more subtle. Haskell attracts programmers who enjoy abstraction, and the language rewards the ability to compress ideas. But a major shared codebase must sometimes resist compression. Readability in this context is not the absence of sophistication. It is sophistication arranged so that another person can enter the argument.

That point also applies to projects outside Haskell. Any mature infrastructure project, whether a database, browser engine, type checker, operating system component, or distributed runtime, eventually discovers that style is governance. It determines what kinds of contributions feel native, what kinds of reasoning are preserved, and how much context must be privately transmitted between insiders. A good style guide lowers the cost of becoming useful.

Counter-perspectives

There is a reasonable counterargument that too much emphasis on style can harden into gatekeeping. If conventions are applied without judgment, they can discourage new contributors, especially when style feedback overshadows the substance of a patch. A project like GHC must therefore balance local coherence against approachability. The goal should be shared readability, not aesthetic policing.

Another counter-perspective is that compiler projects should prefer automated tools wherever possible. This is partly correct. Formatting debates are rarely the best use of scarce reviewer attention, and tools such as Ormolu and Fourmolu show how much friction can be removed by making layout decisions predictable. Yet automation cannot fully replace taste, because the most important style decisions in a compiler concern explanation, decomposition, and the placement of complexity.

A third counterargument is that advanced contributors should be trusted to write advanced code. That is also partly true. GHC’s domain requires sophisticated techniques, and flattening every idea into beginner-friendly code would damage the implementation. But there is a difference between necessary difficulty and accidental opacity. The best compiler code does not pretend the subject is simple. It makes the difficulty legible.

GHC’s coding style page, then, should be read as part of the project’s long-term survival strategy. It asks contributors to treat code as a public record of reasoning, not just a private solution that happens to pass tests. In a compiler that embodies decades of programming language thought, that demand is not bureaucratic. It is the condition under which the thought remains alive.