> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/code-quality/abstractions.md). # Abstractions How to find the domain of your code, and where code belongs: when something gets its own package, file or function, and what its API offers. Owner: Jeremy Code needs to have opinions, and opinions are best exposed through interfaces and abstractions. If you can do everything with an abstraction, you don't need it. This page comes after [Simplicity](/engineering/development-process/how-to-build/coding-standards/code-quality/simplicity.md). Get the structure right here. [Readability](/engineering/development-process/how-to-build/coding-standards/code-quality/readability.md) and then [Code comments](/engineering/development-process/how-to-build/coding-standards/code-quality/code-comments.md) build on it. ## Rules * Before we build something, we find its domain. A domain is a job the industry has a name and tools for, such as process supervision, secrets management or compression. * A domain gets its own package. Inside that package, the size of a piece of code decides whether it gets its own function, file or sub-package. * Folders and files follow the idiomatic layout of the language. * We reuse an existing abstraction before we add a new one. * We remove every exported function or field of an API that no code calls. Each one is more for the caller to read. ## Find the domain first **Identify the domain first, then search for patterns, books and tools in it.** Ask whether the industry has a name for it, and whether there are tools that do only that. Secrets management has Vault and Kubernetes Secrets. Process supervision has S6 and systemd. If it has a name and its own tools, it's a domain. **Before you write a line, look up how those tools do it.** If you do not know the domain yet, ask the code owner which tools to read first. ## Folders, files and functions **Within a domain's package, size decides where code goes.** * A small piece of code stays a function next to the code that uses it. * A bigger piece gets its own file. * A piece too big for one file becomes a sub-package. **Folders follow the idiomatic layout of the language.** We do not invent our own layout. The [Go](/engineering/development-process/how-to-build/coding-standards/languages/go.md) and [Svelte](/engineering/development-process/how-to-build/coding-standards/languages/svelte.md#component-structure) pages describe theirs. ## Hide and reduce **An abstraction either hides or reduces.** Murat Demirbas describes the two kinds in [The Two Abstractions of System Design: Hide or Reduce](https://muratbuffalo.blogspot.com/2026/05/the-two-abstractions-of-system-design.html). * **Hide.** An API hides how something is done. Code that compresses a message only calls a compression API. Which algorithm runs behind it stays hidden. * **Reduce.** An abstraction leaves out everything that is not part of its job. A function that checks a login needs only an email address and a password. It takes those two values, not the whole customer record with its address and order history. The signature then shows what the login depends on. **A clean abstraction limits what you can do with it.** A function that takes a `map[string]any` accepts anything. The caller has to read its code to know what to pass. A function that takes a config type with named fields shows in its signature what it needs. In Go that is a [struct](https://go.dev/ref/spec#Struct_types), in TypeScript an [object type](https://www.typescriptlang.org/docs/handbook/2/objects.html). **Good abstractions also make code secure.** A small API has few ways in, so you can see everything that enters a package and [check it there](/engineering/development-process/how-to-build/coding-standards/architecture/security.md#package-boundaries). ## Reuse before you add **Reuse the abstractions that already exist.** A [spike](/engineering/development-process/how-to-build.md#before-you-write-code) shows them. [Readability](/engineering/development-process/how-to-build/coding-standards/code-quality/readability.md#make-the-code-explain-itself) describes why one concept gets one name. **Only when no existing abstraction fits, add a new one.** Adding fields to an existing struct is not reuse when the new fields belong to something else. When an existing abstraction almost fits, [refactor](/engineering/development-process/how-to-build/coding-standards/code-quality/simplicity.md#prepare-clean-abstractions) it first. ## A readable API **A caller can use an API from its doc comments alone.** The package comment says in which order a caller uses the API. Each parameter is described once, where it is declared. Whatever no code calls is removed. [Code comments](/engineering/development-process/how-to-build/coding-standards/code-quality/code-comments.md) describes the form. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/code-quality/abstractions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.